MQUAD Platform - Unified API Documentation

v2.0.0

Contact: support@mquad.example.com

Base URLs

http://localhost:8000Backend

http://localhost:8001Survey Service

http://localhost:8002Data Service

http://localhost:8003Sync Service

http://localhost:8004Analytics Service

http://localhost:8006Workspace Service

http://localhost:8007Webhook Service

http://localhost:8009ODK Bridge

http://localhost:8010Form Service

http://localhost:8011Media Service

http://localhost:8012Notification Service

http://localhost:8013Audit Service

http://localhost:8014Feature Flags Service

http://localhost:6380Quota Service

Complete API reference for all MQUAD microservices, consolidated from each service's live OpenAPI specification.

Every endpoint is tagged <Service> / <Topic> so the sidebar is grouped by service and then by functional area. Use the server selector on each endpoint to target the correct local service (all services run on localhost; see the Servers list). Microservice-to-microservice calls additionally require the X-Tenant-ID header.

Regenerate with: python3 scripts/merge_openapi_specs.py

Authentication

OAuth2PasswordBeareroauth2

password

Token URL: api/v1/account/login

JWThttp

JWT Token Authentication

Scheme: bearer

HTTPBearerhttp

Scheme: bearer

Backend

Main orchestrator: authentication, users, roles, tenants, billing, app configuration

Backend / Health

Health — Backend

Backend / System Metrics

System Metrics — Backend

Get System Metrics

GET

http://localhost:8000/api/v1/system-metrics

Get System Metrics

curl -X GET 'http://localhost:8000/api/v1/system-metrics' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/system-metrics', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/system-metrics',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "os_metrics": {
    "cpu_percent": 0,
    "memory_percent": 0,
    "memory_total_mb": 0,
    "memory_used_mb": 0
  },
  "celery_metrics": {
    "workers_online": 0,
    "active_tasks": 0,
    "scheduled_tasks": 0,
    "reserved_tasks": 0,
    "worker_details": {}
  }
}

Response

200OKBackend_SystemMetricsResponseDto

Successful Response

Response fields application/json

os_metricsBackend_OSMetricsDtorequired

Show child attributes

cpu_percentnumberrequired

memory_percentnumberrequired

memory_total_mbnumberrequired

memory_used_mbnumberrequired

celery_metricsBackend_CeleryMetricsDto | null

Show child attributes

Any of

workers_onlineintegerrequired

active_tasksintegerrequired

scheduled_tasksintegerrequired

reserved_tasksintegerrequired

worker_detailsobjectrequired

null

Authorization

OAuth2PasswordBeareroauth2

Backend / Tenants

Tenants — Backend

List Tenants

GET

http://localhost:8000/api/v1/tenants

List Tenants

curl -X GET 'http://localhost:8000/api/v1/tenants?skip=0&limit=10' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/tenants?skip=0&limit=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/tenants?skip=0&limit=10',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "subdomain": "string",
      "is_active": true,
      "custom_domain": "string",
      "custom_domain_status": "failed",
      "features": [],
      "subscription_id": "string",
      "plan_tier": "free",
      "is_trial": false,
      "trial_end_at": "string",
      "has_had_trial": false,
      "is_dormant": false,
      "billing_individual_name": "string",
      "billing_business_name": "string",
      "billing_address_line1": "string",
      "billing_address_line2": "string",
      "billing_address_city": "string",
      "billing_address_state": "string",
      "billing_address_postal_code": "string",
      "billing_address_country": "string",
      "tax_id": "string"
    }
  ],
  "skip": 0,
  "limit": 0,
  "total": 0,
  "has_previous": true,
  "has_next": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

skipinteger0query

limitinteger10query

searchstring | nullquery

Response

200OKBackend_TenantListDto

Successful Response

Response fields application/json

itemsArray<Backend_TenantDto>required

Show child attributes

idstring | nullrequired

Show child attributes

Any of

string

null

namestringrequired

subdomainstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

custom_domainstring | nullrequired

Show child attributes

Any of

string

null

custom_domain_statusstringactivefailedactivation-progressfailed

featuresArray<Backend_FeatureDto>

Show child attributes

nameBackend_Featurechatreportanalyticsorganizationteamsstriperequired

enabledbooleanrequired

subscription_idstring | nullrequired

Show child attributes

Any of

string

null

plan_tierstringfree

is_trialbooleanfalse

trial_end_atstring | null

Show child attributes

Any of

string

null

has_had_trialbooleanfalse

is_dormantbooleanfalse

billing_individual_namestring | null

Show child attributes

Any of

string

null

billing_business_namestring | null

Show child attributes

Any of

string

null

billing_address_line1string | null

Show child attributes

Any of

string

null

billing_address_line2string | null

Show child attributes

Any of

string

null

billing_address_citystring | null

Show child attributes

Any of

string

null

billing_address_statestring | null

Show child attributes

Any of

string

null

billing_address_postal_codestring | null

Show child attributes

Any of

string

null

billing_address_countrystring | null

Show child attributes

Any of

string

null

tax_idstring | null

Show child attributes

Any of

string

null

skipintegerrequired

limitintegerrequired

totalintegerrequired

has_previousbooleanrequired

has_nextbooleanrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Create Tenant

POST

http://localhost:8000/api/v1/tenants

Create Tenant

curl -X POST 'http://localhost:8000/api/v1/tenants' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "subdomain": "string",
  "admin_email": "user@example.com",
  "admin_password": "string",
  "first_name": "string",
  "last_name": "string",
  "gender": "male"
}'

const body = `{
  "name": "string",
  "subdomain": "string",
  "admin_email": "user@example.com",
  "admin_password": "string",
  "first_name": "string",
  "last_name": "string",
  "gender": "male"
}`;

const response = await fetch('http://localhost:8000/api/v1/tenants', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "subdomain": "string",
  "admin_email": "user@example.com",
  "admin_password": "string",
  "first_name": "string",
  "last_name": "string",
  "gender": "male"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/tenants',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "subdomain": "string",
  "admin_email": "user@example.com",
  "admin_password": "string",
  "first_name": "string",
  "last_name": "string",
  "gender": "male"
}

{
  "id": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

namestringrequired

subdomainstringrequired

admin_emailstring<email>required

admin_passwordstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

Response

201CreatedBackend_CreateTenantResponseDto

Successful Response

Response fields application/json

idstringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Delete Tenant

DELETE

http://localhost:8000/api/v1/tenants/{id}

Delete Tenant

curl -X DELETE 'http://localhost:8000/api/v1/tenants/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/tenants/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8000/api/v1/tenants/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

idstringrequiredpath

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Search By Name

GET

http://localhost:8000/api/v1/tenants/search_by_name/{name}

Search By Name

curl -X GET 'http://localhost:8000/api/v1/tenants/search_by_name/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/tenants/search_by_name/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/tenants/search_by_name/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "name": "string",
  "subdomain": "string",
  "is_active": true,
  "custom_domain": "string",
  "custom_domain_status": "failed",
  "features": [],
  "subscription_id": "string",
  "plan_tier": "free",
  "is_trial": false,
  "trial_end_at": "string",
  "has_had_trial": false,
  "is_dormant": false,
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

namestringrequiredpath

Response

200OKBackend_TenantDto

Successful Response

Response fields application/json

idstring | nullrequired

Show child attributes

Any of

string

null

namestringrequired

subdomainstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

custom_domainstring | nullrequired

Show child attributes

Any of

string

null

custom_domain_statusstringactivefailedactivation-progressfailed

featuresArray<Backend_FeatureDto>

Show child attributes

nameBackend_Featurechatreportanalyticsorganizationteamsstriperequired

enabledbooleanrequired

subscription_idstring | nullrequired

Show child attributes

Any of

string

null

plan_tierstringfree

is_trialbooleanfalse

trial_end_atstring | null

Show child attributes

Any of

string

null

has_had_trialbooleanfalse

is_dormantbooleanfalse

billing_individual_namestring | null

Show child attributes

Any of

string

null

billing_business_namestring | null

Show child attributes

Any of

string

null

billing_address_line1string | null

Show child attributes

Any of

string

null

billing_address_line2string | null

Show child attributes

Any of

string

null

billing_address_citystring | null

Show child attributes

Any of

string

null

billing_address_statestring | null

Show child attributes

Any of

string

null

billing_address_postal_codestring | null

Show child attributes

Any of

string

null

billing_address_countrystring | null

Show child attributes

Any of

string

null

tax_idstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Search By Subdomain

GET

http://localhost:8000/api/v1/tenants/search_by_subdomain/{subdomain}

Search By Subdomain

curl -X GET 'http://localhost:8000/api/v1/tenants/search_by_subdomain/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/tenants/search_by_subdomain/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/tenants/search_by_subdomain/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "name": "string",
  "subdomain": "string",
  "is_active": true,
  "custom_domain": "string",
  "custom_domain_status": "failed",
  "features": [],
  "subscription_id": "string",
  "plan_tier": "free",
  "is_trial": false,
  "trial_end_at": "string",
  "has_had_trial": false,
  "is_dormant": false,
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

subdomainstringrequiredpath

Response

200OKBackend_TenantDto

Successful Response

Response fields application/json

idstring | nullrequired

Show child attributes

Any of

string

null

namestringrequired

subdomainstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

custom_domainstring | nullrequired

Show child attributes

Any of

string

null

custom_domain_statusstringactivefailedactivation-progressfailed

featuresArray<Backend_FeatureDto>

Show child attributes

nameBackend_Featurechatreportanalyticsorganizationteamsstriperequired

enabledbooleanrequired

subscription_idstring | nullrequired

Show child attributes

Any of

string

null

plan_tierstringfree

is_trialbooleanfalse

trial_end_atstring | null

Show child attributes

Any of

string

null

has_had_trialbooleanfalse

is_dormantbooleanfalse

billing_individual_namestring | null

Show child attributes

Any of

string

null

billing_business_namestring | null

Show child attributes

Any of

string

null

billing_address_line1string | null

Show child attributes

Any of

string

null

billing_address_line2string | null

Show child attributes

Any of

string

null

billing_address_citystring | null

Show child attributes

Any of

string

null

billing_address_statestring | null

Show child attributes

Any of

string

null

billing_address_postal_codestring | null

Show child attributes

Any of

string

null

billing_address_countrystring | null

Show child attributes

Any of

string

null

tax_idstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Check Subdomain Availability

GET

http://localhost:8000/api/v1/tenants/check_subdomain/{subdomain}

Check Subdomain Availability

curl -X GET 'http://localhost:8000/api/v1/tenants/check_subdomain/string'

const response = await fetch('http://localhost:8000/api/v1/tenants/check_subdomain/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8000/api/v1/tenants/check_subdomain/string')
print(response.text)

{
  "is_available": true,
  "reason": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

subdomainstringrequiredpath

Response

200OKBackend_SubdomainAvailabilityDto

Successful Response

Response fields application/json

is_availablebooleanrequired

reasonstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Get Reserved Subdomains

GET

http://localhost:8000/api/v1/tenants/reserved-subdomains

Get list of reserved subdomains that cannot be used for tenant creation.

Get Reserved Subdomains

curl -X GET 'http://localhost:8000/api/v1/tenants/reserved-subdomains'

const response = await fetch('http://localhost:8000/api/v1/tenants/reserved-subdomains', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8000/api/v1/tenants/reserved-subdomains')
print(response.text)

200

{
  "subdomains": [
    "string"
  ]
}

Response

200OKBackend_ReservedSubdomainsDto

Successful Response

Response fields application/json

subdomainsArray<string>required

Update Tenant Dns Record

POST

http://localhost:8000/api/v1/tenants/{tenant_id}/update_dns

When bringing your own domain you must map the DNS records for your custom domain to point to our main domain. You can do this by adding a CNAME record in your domain's DNS settings. Here is an example of how to set it up: Type: CNAME Name: app Value: mquad.local

Update Tenant Dns Record

curl -X POST 'http://localhost:8000/api/v1/tenants/string/update_dns' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "is_active": true,
  "is_dormant": true,
  "custom_domain": "string",
  "subscription_id": "string",
  "plan_tier": "string",
  "custom_domain_status": "active",
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}'

const body = `{
  "is_active": true,
  "is_dormant": true,
  "custom_domain": "string",
  "subscription_id": "string",
  "plan_tier": "string",
  "custom_domain_status": "active",
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/tenants/string/update_dns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "is_active": true,
  "is_dormant": true,
  "custom_domain": "string",
  "subscription_id": "string",
  "plan_tier": "string",
  "custom_domain_status": "active",
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/tenants/string/update_dns',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "is_active": true,
  "is_dormant": true,
  "custom_domain": "string",
  "subscription_id": "string",
  "plan_tier": "string",
  "custom_domain_status": "active",
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

is_activeboolean | null

Show child attributes

Any of

boolean

null

is_dormantboolean | null

Show child attributes

Any of

boolean

null

custom_domainstring | null

Show child attributes

Any of

string

null

subscription_idstring | null

Show child attributes

Any of

string

null

plan_tierstring | null

Show child attributes

Any of

string

null

custom_domain_statusstring | null

Show child attributes

Any of

stringactivefailedactivation-progress

null

billing_individual_namestring | null

Show child attributes

Any of

string

null

billing_business_namestring | null

Show child attributes

Any of

string

null

billing_address_line1string | null

Show child attributes

Any of

string

null

billing_address_line2string | null

Show child attributes

Any of

string

null

billing_address_citystring | null

Show child attributes

Any of

string

null

billing_address_statestring | null

Show child attributes

Any of

string

null

billing_address_postal_codestring | null

Show child attributes

Any of

string

null

billing_address_countrystring | null

Show child attributes

Any of

string

null

tax_idstring | null

Show child attributes

Any of

string

null

Parameters

tenant_idstringrequiredpath

Response

202AcceptedBackend_UpdateTenantResponseDto

Successful Response

Response fields application/json

messagestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Check Dns Status

GET

http://localhost:8000/api/v1/tenants/{tenant_id}/check_dns

Check Dns Status

curl -X GET 'http://localhost:8000/api/v1/tenants/string/check_dns' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/tenants/string/check_dns', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/tenants/string/check_dns',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_UpdateTenantResponseDto

Successful Response

Response fields application/json

messagestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get Dns Details

GET

http://localhost:8000/api/v1/tenants/{tenant_id}/dns-details

Get detailed DNS information for a tenant.

Get Dns Details

curl -X GET 'http://localhost:8000/api/v1/tenants/string/dns-details' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/tenants/string/dns-details', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/tenants/string/dns-details',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "name": "string",
  "subdomain": "string",
  "is_active": true,
  "custom_domain": "string",
  "custom_domain_status": "failed",
  "features": [],
  "subscription_id": "string",
  "plan_tier": "free",
  "is_trial": false,
  "trial_end_at": "string",
  "has_had_trial": false,
  "is_dormant": false,
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_TenantDto

Successful Response

Response fields application/json

idstring | nullrequired

Show child attributes

Any of

string

null

namestringrequired

subdomainstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

custom_domainstring | nullrequired

Show child attributes

Any of

string

null

custom_domain_statusstringactivefailedactivation-progressfailed

featuresArray<Backend_FeatureDto>

Show child attributes

nameBackend_Featurechatreportanalyticsorganizationteamsstriperequired

enabledbooleanrequired

subscription_idstring | nullrequired

Show child attributes

Any of

string

null

plan_tierstringfree

is_trialbooleanfalse

trial_end_atstring | null

Show child attributes

Any of

string

null

has_had_trialbooleanfalse

is_dormantbooleanfalse

billing_individual_namestring | null

Show child attributes

Any of

string

null

billing_business_namestring | null

Show child attributes

Any of

string

null

billing_address_line1string | null

Show child attributes

Any of

string

null

billing_address_line2string | null

Show child attributes

Any of

string

null

billing_address_citystring | null

Show child attributes

Any of

string

null

billing_address_statestring | null

Show child attributes

Any of

string

null

billing_address_postal_codestring | null

Show child attributes

Any of

string

null

billing_address_countrystring | null

Show child attributes

Any of

string

null

tax_idstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update Tenant

PUT

http://localhost:8000/api/v1/tenants/{tenant_id}

Update Tenant

curl -X PUT 'http://localhost:8000/api/v1/tenants/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "is_active": true,
  "is_dormant": true,
  "custom_domain": "string",
  "subscription_id": "string",
  "plan_tier": "string",
  "custom_domain_status": "active",
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}'

const body = `{
  "is_active": true,
  "is_dormant": true,
  "custom_domain": "string",
  "subscription_id": "string",
  "plan_tier": "string",
  "custom_domain_status": "active",
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/tenants/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "is_active": true,
  "is_dormant": true,
  "custom_domain": "string",
  "subscription_id": "string",
  "plan_tier": "string",
  "custom_domain_status": "active",
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}'''

response = requests.put(
    'http://localhost:8000/api/v1/tenants/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "is_active": true,
  "is_dormant": true,
  "custom_domain": "string",
  "subscription_id": "string",
  "plan_tier": "string",
  "custom_domain_status": "active",
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

is_activeboolean | null

Show child attributes

Any of

boolean

null

is_dormantboolean | null

Show child attributes

Any of

boolean

null

custom_domainstring | null

Show child attributes

Any of

string

null

subscription_idstring | null

Show child attributes

Any of

string

null

plan_tierstring | null

Show child attributes

Any of

string

null

custom_domain_statusstring | null

Show child attributes

Any of

stringactivefailedactivation-progress

null

billing_individual_namestring | null

Show child attributes

Any of

string

null

billing_business_namestring | null

Show child attributes

Any of

string

null

billing_address_line1string | null

Show child attributes

Any of

string

null

billing_address_line2string | null

Show child attributes

Any of

string

null

billing_address_citystring | null

Show child attributes

Any of

string

null

billing_address_statestring | null

Show child attributes

Any of

string

null

billing_address_postal_codestring | null

Show child attributes

Any of

string

null

billing_address_countrystring | null

Show child attributes

Any of

string

null

tax_idstring | null

Show child attributes

Any of

string

null

Parameters

tenant_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get Tenant Features

GET

http://localhost:8000/api/v1/tenants/{tenant_id}/features

Get Tenant Features

curl -X GET 'http://localhost:8000/api/v1/tenants/string/features' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/tenants/string/features', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/tenants/string/features',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

[
  {
    "name": "chat",
    "enabled": true
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKArray<Backend_FeatureDto>

Successful Response

Response fields application/json

Array<Backend_FeatureDto>

Show child attributes

nameBackend_Featurechatreportanalyticsorganizationteamsstriperequired

enabledbooleanrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update Tenant Feature

PATCH

http://localhost:8000/api/v1/tenants/{tenant_id}/update_feature

Update Tenant Feature

curl -X PATCH 'http://localhost:8000/api/v1/tenants/string/update_feature' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "chat",
  "enabled": true
}'

const body = `{
  "name": "chat",
  "enabled": true
}`;

const response = await fetch('http://localhost:8000/api/v1/tenants/string/update_feature', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "chat",
  "enabled": true
}'''

response = requests.patch(
    'http://localhost:8000/api/v1/tenants/string/update_feature',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "chat",
  "enabled": true
}

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

nameBackend_Featurechatreportanalyticsorganizationteamsstriperequired

enabledbooleanrequired

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_UpdateTenantResponseDto

Successful Response

Response fields application/json

messagestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Activate Trial Plan

PATCH

http://localhost:8000/api/v1/tenants/{tenant_id}/activate_trial_plan

Activate a trial subscription by creating a real Stripe subscription.

Activate Trial Plan

curl -X PATCH 'http://localhost:8000/api/v1/tenants/string/activate_trial_plan' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "address": {
    "individual_name": "string",
    "business_name": "string",
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string"
  },
  "tax_id": "string"
}'

const body = `{
  "address": {
    "individual_name": "string",
    "business_name": "string",
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string"
  },
  "tax_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/tenants/string/activate_trial_plan', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "address": {
    "individual_name": "string",
    "business_name": "string",
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string"
  },
  "tax_id": "string"
}'''

response = requests.patch(
    'http://localhost:8000/api/v1/tenants/string/activate_trial_plan',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "address": {
    "individual_name": "string",
    "business_name": "string",
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string"
  },
  "tax_id": "string"
}

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

Any of

addressBackend_BillingAddressDtorequired

Show child attributes

individual_namestringrequired

business_namestring | null

Show child attributes

Any of

string

null

line1stringrequired

line2string | null

Show child attributes

Any of

string

null

citystringrequired

statestringrequired

postal_codestringrequired

countrystringrequired

tax_idstring | null

Show child attributes

Any of

string

null

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_UpdateTenantResponseDto

Successful Response

Response fields application/json

messagestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update Tenant Billing Address

PUT

http://localhost:8000/api/v1/tenants/{tenant_id}/billing-address

Update tenant billing address and optionally tax ID.

Update Tenant Billing Address

curl -X PUT 'http://localhost:8000/api/v1/tenants/string/billing-address' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "address": {
    "individual_name": "string",
    "business_name": "string",
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string"
  },
  "tax_id": "string"
}'

const body = `{
  "address": {
    "individual_name": "string",
    "business_name": "string",
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string"
  },
  "tax_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/tenants/string/billing-address', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "address": {
    "individual_name": "string",
    "business_name": "string",
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string"
  },
  "tax_id": "string"
}'''

response = requests.put(
    'http://localhost:8000/api/v1/tenants/string/billing-address',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "address": {
    "individual_name": "string",
    "business_name": "string",
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string"
  },
  "tax_id": "string"
}

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

addressBackend_BillingAddressDtorequired

Show child attributes

individual_namestringrequired

business_namestring | null

Show child attributes

Any of

string

null

line1stringrequired

line2string | null

Show child attributes

Any of

string

null

citystringrequired

statestringrequired

postal_codestringrequired

countrystringrequired

tax_idstring | null

Show child attributes

Any of

string

null

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_UpdateTenantResponseDto

Successful Response

Response fields application/json

messagestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get Tenant Plan Tier

GET

http://localhost:8000/api/v1/tenants/{tenant_id}/plan-tier

Get the plan tier for a tenant.

Get Tenant Plan Tier

curl -X GET 'http://localhost:8000/api/v1/tenants/string/plan-tier'

const response = await fetch('http://localhost:8000/api/v1/tenants/string/plan-tier', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8000/api/v1/tenants/string/plan-tier')
print(response.text)

{
  "tier": "string",
  "name": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_PlanTierResponseDto

Successful Response

Response fields application/json

tierstringrequired

namestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Get Tenant Plan Context

GET

http://localhost:8000/api/v1/tenants/{tenant_id}/plan-context

Return tenant billing state used by feature-flags-service plan resolution.

Get Tenant Plan Context

curl -X GET 'http://localhost:8000/api/v1/tenants/string/plan-context'

const response = await fetch('http://localhost:8000/api/v1/tenants/string/plan-context', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8000/api/v1/tenants/string/plan-context')
print(response.text)

{
  "tenant_id": "string",
  "tier": "string",
  "name": "string",
  "subscription_status": "inactive",
  "is_active": false,
  "is_trial": false,
  "trial_end_at": "string",
  "is_dormant": false,
  "features": [
    {}
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_TenantPlanContextResponseDto

Successful Response

Response fields application/json

tenant_idstringrequired

tierstringrequired

namestringrequired

subscription_statusstringinactive

is_activebooleanfalse

is_trialbooleanfalse

trial_end_atstring | null

Show child attributes

Any of

string

null

is_dormantbooleanfalse

featuresArray<object>

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Enterprise Signup

POST

http://localhost:8000/api/v1/tenants/{tenant_id}/enterprise-signup

Submit an enterprise plan inquiry. Sends the inquiry to the sales team via notification-service using the enterprise_signup template. Uses tenant admin's name and tenant name as defaults.

Enterprise Signup

curl -X POST 'http://localhost:8000/api/v1/tenants/string/enterprise-signup' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "email": "user@example.com",
  "company": "string",
  "phone": "string",
  "message": "string",
  "tenant_id": "string"
}'

const body = `{
  "name": "string",
  "email": "user@example.com",
  "company": "string",
  "phone": "string",
  "message": "string",
  "tenant_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/tenants/string/enterprise-signup', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "email": "user@example.com",
  "company": "string",
  "phone": "string",
  "message": "string",
  "tenant_id": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/tenants/string/enterprise-signup',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "email": "user@example.com",
  "company": "string",
  "phone": "string",
  "message": "string",
  "tenant_id": "string"
}

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

Response

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

Cancel Tenant Subscription

POST

http://localhost:8000/api/v1/tenants/{tenant_id}/cancel-subscription

Host admin endpoint to cancel a tenant's Stripe subscription. Downgrades the tenant to Free plan and clears dormant state.

Cancel Tenant Subscription

curl -X POST 'http://localhost:8000/api/v1/tenants/string/cancel-subscription' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/tenants/string/cancel-subscription', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/tenants/string/cancel-subscription',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_UpdateTenantResponseDto

Successful Response

Response fields application/json

messagestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Features

Features — Backend

List Features

GET

http://localhost:8000/api/v1/features

List all available features. Requires HOST_MANAGE_TENANTS permission.

List Features

curl -X GET 'http://localhost:8000/api/v1/features' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/features', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/features',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

[
  "chat"
]

Response

200OKArray<Backend_Feature>chatreportanalyticsorganizationteamsstripe

Successful Response

Response fields application/json

Array<Backend_Feature>chatreportanalyticsorganizationteamsstripe

Authorization

OAuth2PasswordBeareroauth2

Backend / App Configuration

App Configuration — Backend

Get App Configuration

GET

http://localhost:8000/api/v1/app_configuration

Get App Configuration

curl -X GET 'http://localhost:8000/api/v1/app_configuration' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/app_configuration', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/app_configuration',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "is_multi_tenant_enabled": true,
  "multi_tenancy_strategy": "string",
  "host_main_domain": "string",
  "is_user_logged_in": false,
  "user_preferences": {
    "user_id": "string",
    "preferences": {}
  },
  "current_tenant": {
    "id": "string",
    "name": "string",
    "subdomain": "string",
    "is_active": true,
    "custom_domain": "string",
    "custom_domain_status": "failed",
    "features": [],
    "subscription_id": "string",
    "plan_tier": "free",
    "is_trial": false,
    "trial_end_at": "string",
    "has_had_trial": false,
    "is_dormant": false,
    "billing_individual_name": "string",
    "billing_business_name": "string",
    "billing_address_line1": "string",
    "billing_address_line2": "string",
    "billing_address_city": "string",
    "billing_address_state": "string",
    "billing_address_postal_code": "string",
    "billing_address_country": "string",
    "tax_id": "string"
  },
  "environment": "string",
  "runtime_security_config": {
    "screenshot_prevention_mode": "disabled",
    "root_detection_mode": "warning",
    "biometric_required_mode": "disabled",
    "session_timeout_minutes": 0,
    "wifi_only_sync": false,
    "battery_aware_sync": false,
    "battery_low_threshold_percent": 20,
    "block_sync_on_roaming": false,
    "background_sync_enabled": true,
    "crash_reporting_enabled": true,
    "telemetry_enabled": true,
    "global_mode": "warning",
    "version_id": "string"
  },
  "tenant_data_governances": [
    {
      "tenant_id": "string",
      "max_offline_duration_hours": 0,
      "force_revalidation_hours": 0,
      "media_upload_max_size_mb": 50,
      "media_upload_allowed_types": [
        "string"
      ],
      "local_retention_days": 0,
      "remote_wipe_enabled": false,
      "version_id": "string"
    }
  ],
  "mobile_security_policy": {
    "global_mode": "warning",
    "screenshot_prevention_mode": "disabled",
    "root_detection_mode": "warning",
    "max_offline_duration_hours": 0,
    "force_revalidation_hours": 0,
    "media_upload_max_size_mb": 50,
    "media_upload_allowed_types": [],
    "wifi_only_sync": false,
    "battery_aware_sync": false,
    "battery_low_threshold_percent": 20,
    "block_sync_on_roaming": false,
    "local_retention_days": 0,
    "remote_wipe_enabled": false,
    "biometric_required_mode": "disabled",
    "session_timeout_minutes": 0
  }
}

Response

200OKBackend_AppConfigurationDto

Successful Response

Response fields application/json

is_multi_tenant_enabledbooleanrequired

multi_tenancy_strategystringrequired

host_main_domainstringrequired

is_user_logged_inboolean | nullfalse

Show child attributes

Any of

boolean

null

user_preferencesBackend_UserPreferenceDto | null

Show child attributes

Any of

user_idstringrequired

preferencesobjectrequired

null

current_tenantBackend_TenantDto | null

Show child attributes

Any of

idstring | nullrequired

Show child attributes

Any of

string

null

namestringrequired

subdomainstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

custom_domainstring | nullrequired

Show child attributes

Any of

string

null

custom_domain_statusstringactivefailedactivation-progressfailed

featuresArray<Backend_FeatureDto>

Show child attributes

nameBackend_Featurechatreportanalyticsorganizationteamsstriperequired

enabledbooleanrequired

subscription_idstring | nullrequired

Show child attributes

Any of

string

null

plan_tierstringfree

is_trialbooleanfalse

trial_end_atstring | null

Show child attributes

Any of

string

null

has_had_trialbooleanfalse

is_dormantbooleanfalse

billing_individual_namestring | null

Show child attributes

Any of

string

null

billing_business_namestring | null

Show child attributes

Any of

string

null

billing_address_line1string | null

Show child attributes

Any of

string

null

billing_address_line2string | null

Show child attributes

Any of

string

null

billing_address_citystring | null

Show child attributes

Any of

string

null

billing_address_statestring | null

Show child attributes

Any of

string

null

billing_address_postal_codestring | null

Show child attributes

Any of

string

null

billing_address_countrystring | null

Show child attributes

Any of

string

null

tax_idstring | null

Show child attributes

Any of

string

null

environmentstringrequired

runtime_security_configBackend_RuntimeSecurityConfigConfigDto | null

Show child attributes

Any of

screenshot_prevention_modestringdisabled

root_detection_modestringwarning

biometric_required_modestringdisabled

session_timeout_minutesinteger0

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

background_sync_enabledbooleantrue

crash_reporting_enabledbooleantrue

telemetry_enabledbooleantrue

global_modestringwarning

version_idstring | null

Show child attributes

Any of

string

null

tenant_data_governancesArray<Backend_TenantDataGovernanceConfigDto> | null

Show child attributes

Any of

Array<Backend_TenantDataGovernanceConfigDto>

Show child attributes

tenant_idstringrequired

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<string> | null

Show child attributes

Any of

Array<string>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

version_idstring | null

Show child attributes

Any of

string

null

mobile_security_policyBackend_DeprecatedMobileSecurityPolicyConfigDto | null

Show child attributes

Any of

DEPRECATED: For old mobile clients. Remove after migration window.

global_modestringwarning

screenshot_prevention_modestringdisabled

root_detection_modestringwarning

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

biometric_required_modestringdisabled

session_timeout_minutesinteger0

null

Authorization

OAuth2PasswordBeareroauth2

Backend / Account

Account — Backend

Login New

POST

http://localhost:8000/api/v1/account/login/new

New login endpoint - authenticate and return user info with tenant list. Does not require tenant selection. User selects tenant in separate step.

curl -X POST 'http://localhost:8000/api/v1/account/login/new' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string'

const response = await fetch('http://localhost:8000/api/v1/account/login/new', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: 'grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string',
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/account/login/new',
    data='grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string'.encode('utf-8'),
    headers={
        'Content-Type': 'application/x-www-form-urlencoded',
    },
)
print(response.text)

Request Body

{
  "grant_type": "string",
  "username": "string",
  "password": "********",
  "scope": "",
  "client_id": "string",
  "client_secret": "string"
}

{
  "user": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url": "string",
    "is_active": true,
    "activated_at": "2024-01-15T09:30:00Z",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    },
    "user_code": "string"
  },
  "tenants": [
    {
      "id": "string",
      "name": "string",
      "subdomain": "string",
      "custom_domain": "string",
      "logo_url": "string",
      "role": {
        "id": "string",
        "name": "string",
        "description": "string",
        "permissions": [],
        "is_immutable": false,
        "created_at": "string",
        "updated_at": "string",
        "tenant_id": "string",
        "scope": "tenant_custom",
        "users_count": 0
      }
    }
  ],
  "requires_tenant_selection": true,
  "is_super_admin": true,
  "message": "Login successful",
  "token": "string",
  "refresh_token": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/x-www-form-urlencoded

grant_typestring | null

Show child attributes

Any of

string

null

usernamestringrequired

passwordstring<password>required

scopestring

client_idstring | null

Show child attributes

Any of

string

null

client_secretstring | null<password>

Show child attributes

Any of

string

null

Response

200OKBackend_LoginResponseDto

Successful Response

Response fields application/json

Response after successful login with tenant selection info

userBackend_UserInfoDtorequired

User information returned after login

Show child attributes

idstringrequired

emailstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

permissionsArray<Backend_Permission>super:adminfull:accessuser:read_and_write_onlyuser:delete_onlyuser:self_read_and_write_onlyuser:role_assign_or_remove_onlyuser:view_onlyrole:view_onlyrole:read_and_write_onlyrole:delete_onlyrole:permission_read_and_write_onlyhost:manage_tenantsmanage:storage_settingsmanage:tenant_settingsmanage:billingmanage:payments_settingsmanage:products_and_pricingaudit_logs:view_onlyaudit_logs:downloadaudit_logs:writecompliance:manageforms:renderforms:previewforms:render_anonymousforms:submitforms:submit_anonymousforms:submit_offlineforms:draft_createforms:draft_readforms:draft_updateforms:draft_deleteforms:draft_read_allforms:session_createforms:session_readforms:session_deleteforms:session_read_allforms:config_readforms:config_writeforms:analytics_viewforms:analytics_exportforms:admindashboard:viewdashboard:readdashboard:createdashboard:updatedashboard:deletebilling:readconfig:readconfig:writesurvey:managesurvey:createsurvey:readsurvey:updatesurvey:deletesurvey:publishsurvey:unpublishsurvey:grant_accesssurvey:manage_accesssurvey:response_viewsurvey:response_downloadtemplate:readtemplate:createtemplate:updatetemplate:deletetemplate:managesubmission:createsubmission:readsubmission:updatesubmission:update_ownsubmission:deletesubmission:viewsubmission:exportsubmission:approvesubmission:assignworkspace:createworkspace:readworkspace:updateworkspace:deleteworkspace:manageworkspace:manage_membersproject:createproject:readproject:updateproject:deleteproject:manageanalytics:viewanalytics:exportanalytics:adminreport:viewreport:createexport:createexport:viewexport:downloadexport:cancelexport:template:createexport:template:viewwebhook:createwebhook:readwebhook:updatewebhook:deletewebhook:managesearch:executesearch:managenotification:sendnotification:viewnotification:read_allnotification:deletenotification:managenotification:template:viewnotification:template:createnotification:template:updatenotification:template:deletenotification:preferences:readnotification:preferences:writemedia:uploadmedia:readmedia:updatemedia:deletemedia:library_uploadmedia:library_readmedia:library_deletemedia:managefeature_flag:readfeature_flag:createfeature_flag:updatefeature_flag:deletefeature_flag:toggleresponse:createresponse:readresponse:updateresponse:deleteresponse:exportresponse:approveresponse:revise_ownattachment:createattachment:readattachment:deleteodk:viewodk:submitodk:manage

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

user_codestring | null

Show child attributes

Any of

string

null

tenantsArray<Backend_TenantInfoDto>required

Show child attributes

Tenant information for selection

idstringrequired

namestringrequired

subdomainstring | null

Show child attributes

Any of

string

null

custom_domainstring | null

Show child attributes

Any of

string

null

logo_urlstring | null

Show child attributes

Any of

string

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

requires_tenant_selectionbooleanrequired

is_super_adminbooleanrequired

messagestringLogin successful

tokenstring | null

Show child attributes

Any of

string

null

refresh_tokenstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Login Super Admin

POST

http://localhost:8000/api/v1/account/login/super-admin

Super admin login endpoint - authenticate and return tokens directly. Super admins have system-wide access without tenant selection.

curl -X POST 'http://localhost:8000/api/v1/account/login/super-admin' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string'

const response = await fetch('http://localhost:8000/api/v1/account/login/super-admin', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: 'grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string',
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/account/login/super-admin',
    data='grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string'.encode('utf-8'),
    headers={
        'Content-Type': 'application/x-www-form-urlencoded',
    },
)
print(response.text)

Request Body

{
  "grant_type": "string",
  "username": "string",
  "password": "********",
  "scope": "",
  "client_id": "string",
  "client_secret": "string"
}

{
  "access_token": "string",
  "token_type": "bearer",
  "expires_in": 0,
  "refresh_token": "string",
  "refresh_token_expires_in": 0,
  "user": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url": "string",
    "is_active": true,
    "activated_at": "2024-01-15T09:30:00Z",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    },
    "user_code": "string"
  },
  "tenant": {
    "id": "string",
    "name": "string",
    "subdomain": "string",
    "custom_domain": "string",
    "logo_url": "string",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    }
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/x-www-form-urlencoded

grant_typestring | null

Show child attributes

Any of

string

null

usernamestringrequired

passwordstring<password>required

scopestring

client_idstring | null

Show child attributes

Any of

string

null

client_secretstring | null<password>

Show child attributes

Any of

string

null

Response

200OKBackend_TenantSelectionResponseDto

Successful Response

Response fields application/json

Response after tenant selection with tokens

access_tokenstringrequired

token_typestringbearer

expires_inintegerrequired

refresh_tokenstringrequired

refresh_token_expires_inintegerrequired

userBackend_UserInfoDtorequired

User information returned after login

Show child attributes

idstringrequired

emailstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

user_codestring | null

Show child attributes

Any of

string

null

tenantBackend_TenantInfoDto | null

Show child attributes

Any of

Tenant information for selection

idstringrequired

namestringrequired

subdomainstring | null

Show child attributes

Any of

string

null

custom_domainstring | null

Show child attributes

Any of

string

null

logo_urlstring | null

Show child attributes

Any of

string

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Login Host Admin

POST

http://localhost:8000/api/v1/account/login/host-admin

Host admin login endpoint - for users without a specific tenant (host-level access). Returns tokens for users who have access to the host system but no tenant.

curl -X POST 'http://localhost:8000/api/v1/account/login/host-admin' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string'

const response = await fetch('http://localhost:8000/api/v1/account/login/host-admin', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: 'grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string',
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/account/login/host-admin',
    data='grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string'.encode('utf-8'),
    headers={
        'Content-Type': 'application/x-www-form-urlencoded',
    },
)
print(response.text)

Request Body

{
  "grant_type": "string",
  "username": "string",
  "password": "********",
  "scope": "",
  "client_id": "string",
  "client_secret": "string"
}

{
  "access_token": "string",
  "token_type": "bearer",
  "expires_in": 0,
  "refresh_token": "string",
  "refresh_token_expires_in": 0,
  "user": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url": "string",
    "is_active": true,
    "activated_at": "2024-01-15T09:30:00Z",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    },
    "user_code": "string"
  },
  "tenant": {
    "id": "string",
    "name": "string",
    "subdomain": "string",
    "custom_domain": "string",
    "logo_url": "string",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    }
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/x-www-form-urlencoded

grant_typestring | null

Show child attributes

Any of

string

null

usernamestringrequired

passwordstring<password>required

scopestring

client_idstring | null

Show child attributes

Any of

string

null

client_secretstring | null<password>

Show child attributes

Any of

string

null

Response

200OKBackend_TenantSelectionResponseDto

Successful Response

Response fields application/json

Response after tenant selection with tokens

access_tokenstringrequired

token_typestringbearer

expires_inintegerrequired

refresh_tokenstringrequired

refresh_token_expires_inintegerrequired

userBackend_UserInfoDtorequired

User information returned after login

Show child attributes

idstringrequired

emailstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

user_codestring | null

Show child attributes

Any of

string

null

tenantBackend_TenantInfoDto | null

Show child attributes

Any of

Tenant information for selection

idstringrequired

namestringrequired

subdomainstring | null

Show child attributes

Any of

string

null

custom_domainstring | null

Show child attributes

Any of

string

null

logo_urlstring | null

Show child attributes

Any of

string

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Select Tenant

POST

http://localhost:8000/api/v1/account/select-tenant

After login, select a tenant and get access tokens. Super admins skip tenant selection.

Select Tenant

curl -X POST 'http://localhost:8000/api/v1/account/select-tenant' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "tenant_id": "string"
}'

const body = `{
  "tenant_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/account/select-tenant', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "tenant_id": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/account/select-tenant',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "tenant_id": "string"
}

{
  "access_token": "string",
  "token_type": "bearer",
  "expires_in": 0,
  "refresh_token": "string",
  "refresh_token_expires_in": 0,
  "user": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url": "string",
    "is_active": true,
    "activated_at": "2024-01-15T09:30:00Z",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    },
    "user_code": "string"
  },
  "tenant": {
    "id": "string",
    "name": "string",
    "subdomain": "string",
    "custom_domain": "string",
    "logo_url": "string",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    }
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

Request to select a tenant and get tokens

tenant_idstringrequired

Response

200OKBackend_TenantSelectionResponseDto

Successful Response

Response fields application/json

Response after tenant selection with tokens

access_tokenstringrequired

token_typestringbearer

expires_inintegerrequired

refresh_tokenstringrequired

refresh_token_expires_inintegerrequired

userBackend_UserInfoDtorequired

User information returned after login

Show child attributes

idstringrequired

emailstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

user_codestring | null

Show child attributes

Any of

string

null

tenantBackend_TenantInfoDto | null

Show child attributes

Any of

Tenant information for selection

idstringrequired

namestringrequired

subdomainstring | null

Show child attributes

Any of

string

null

custom_domainstring | null

Show child attributes

Any of

string

null

logo_urlstring | null

Show child attributes

Any of

string

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Switch Tenant

POST

http://localhost:8000/api/v1/account/switch-tenant

Switch the user's active tenant mid-session. Requires a valid session token (not a pre-auth token). Issues entirely new access + refresh tokens scoped to the target tenant. The previous tenant_id comes from the current JWT's tenant_id claim.

Switch Tenant

curl -X POST 'http://localhost:8000/api/v1/account/switch-tenant' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "tenant_id": "string"
}'

const body = `{
  "tenant_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/account/switch-tenant', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "tenant_id": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/account/switch-tenant',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "tenant_id": "string"
}

{
  "access_token": "string",
  "token_type": "bearer",
  "expires_in": 0,
  "refresh_token": "string",
  "refresh_token_expires_in": 0,
  "user": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url": "string",
    "is_active": true,
    "activated_at": "2024-01-15T09:30:00Z",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    },
    "user_code": "string"
  },
  "tenant": {
    "id": "string",
    "name": "string",
    "subdomain": "string",
    "custom_domain": "string",
    "logo_url": "string",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    }
  },
  "previous_tenant_id": "string",
  "message": "Tenant switched successfully"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

Request to switch active tenant

tenant_idstringrequired

Response

200OKBackend_SwitchTenantResponseDto

Successful Response

Response fields application/json

Response after switching tenant with new tokens and context

access_tokenstringrequired

token_typestringbearer

expires_inintegerrequired

refresh_tokenstringrequired

refresh_token_expires_inintegerrequired

userBackend_UserInfoDtorequired

User information returned after login

Show child attributes

idstringrequired

emailstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

user_codestring | null

Show child attributes

Any of

string

null

tenantBackend_TenantInfoDtorequired

Tenant information for selection

Show child attributes

idstringrequired

namestringrequired

subdomainstring | null

Show child attributes

Any of

string

null

custom_domainstring | null

Show child attributes

Any of

string

null

logo_urlstring | null

Show child attributes

Any of

string

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

previous_tenant_idstring | null

Show child attributes

Any of

string

null

messagestringTenant switched successfully

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Login

POST

http://localhost:8000/api/v1/account/login

curl -X POST 'http://localhost:8000/api/v1/account/login' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-raw 'grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string'

const response = await fetch('http://localhost:8000/api/v1/account/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: 'grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string',
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/account/login',
    data='grant_type=string&username=string&password=%2A%2A%2A%2A%2A%2A%2A%2A&scope=&client_id=string&client_secret=string'.encode('utf-8'),
    headers={
        'Content-Type': 'application/x-www-form-urlencoded',
    },
)
print(response.text)

Request Body

{
  "grant_type": "string",
  "username": "string",
  "password": "********",
  "scope": "",
  "client_id": "string",
  "client_secret": "string"
}

{
  "refresh_token": "string",
  "refresh_token_expires_in": 0,
  "access_token": "string",
  "token_type": "string",
  "expires_in": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/x-www-form-urlencoded

grant_typestring | null

Show child attributes

Any of

string

null

usernamestringrequired

passwordstring<password>required

scopestring

client_idstring | null

Show child attributes

Any of

string

null

client_secretstring | null<password>

Show child attributes

Any of

string

null

Response

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Refresh Token

POST

http://localhost:8000/api/v1/account/refresh

Refresh Token

curl -X POST 'http://localhost:8000/api/v1/account/refresh'

const response = await fetch('http://localhost:8000/api/v1/account/refresh', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8000/api/v1/account/refresh')
print(response.text)

{
  "refresh_token": "string",
  "refresh_token_expires_in": 0,
  "access_token": "string",
  "token_type": "string",
  "expires_in": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

Response

200OKBackend_TokenSetDto

Successful Response

Response fields application/json

refresh_tokenstringrequired

refresh_token_expires_inintegerrequired

access_tokenstringrequired

token_typestringrequired

expires_inintegerrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Logout

GET

http://localhost:8000/api/v1/account/logout

Logout

curl -X GET 'http://localhost:8000/api/v1/account/logout' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/account/logout', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/account/logout',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Authorization

OAuth2PasswordBeareroauth2

Logout

POST

http://localhost:8000/api/v1/account/logout

Logout

curl -X POST 'http://localhost:8000/api/v1/account/logout' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/account/logout', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/account/logout',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Authorization

OAuth2PasswordBeareroauth2

Register

POST

http://localhost:8000/api/v1/account/register

curl -X POST 'http://localhost:8000/api/v1/account/register' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "prefer_not_to_say",
  "tenant_id": "string",
  "role_id": "string",
  "password": "string",
  "sub_domain": "string",
  "agreed_to_terms": true
}'

const body = `{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "prefer_not_to_say",
  "tenant_id": "string",
  "role_id": "string",
  "password": "string",
  "sub_domain": "string",
  "agreed_to_terms": true
}`;

const response = await fetch('http://localhost:8000/api/v1/account/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "prefer_not_to_say",
  "tenant_id": "string",
  "role_id": "string",
  "password": "string",
  "sub_domain": "string",
  "agreed_to_terms": true
}'''

response = requests.post(
    'http://localhost:8000/api/v1/account/register',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "prefer_not_to_say",
  "tenant_id": "string",
  "role_id": "string",
  "password": "string",
  "sub_domain": "string",
  "agreed_to_terms": true
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gender | nullprefer_not_to_say

Show child attributes

Any of

Backend_Gendermalefemaleotherprefer_not_to_say

null

tenant_idstring | null

Show child attributes

Any of

string

null

role_idstring | null

Show child attributes

Any of

string

null

passwordstringrequired

sub_domainstring | null

Show child attributes

Any of

string

null

agreed_to_termsbooleantrue

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Read Users Me

GET

http://localhost:8000/api/v1/account/me

Read Users Me

curl -X GET 'http://localhost:8000/api/v1/account/me' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/account/me', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/account/me',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "id": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "role_id": "string",
  "role_name": "string",
  "is_active": true,
  "member_active": true,
  "activated_at": "string",
  "image_url": "string",
  "user_code": "string",
  "created_at": "string",
  "updated_at": "string",
  "tenant_id": "string",
  "permissions": [
    "string"
  ],
  "agreed_to_terms": false,
  "role": {
    "id": "string",
    "name": "string",
    "description": "string",
    "permissions": [],
    "is_immutable": false,
    "created_at": "string",
    "updated_at": "string",
    "tenant_id": "string",
    "scope": "tenant_custom",
    "users_count": 0
  },
  "subscription": {
    "id": "string",
    "plan_levels": {},
    "is_trial": true,
    "tenant_id": "string",
    "actor": "string",
    "user_id": "string",
    "plan_id": "string",
    "plan_name": "string",
    "stripe_subscription_status": "string",
    "trial_end_at": "string"
  }
}

Response

200OKBackend_MeResponseDto

Successful Response

Response fields application/json

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

roleBackend_RoleDtorequired

Show child attributes

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

subscriptionBackend_SubscriptionPlanDto | nullrequired

Show child attributes

Any of

idstringrequired

plan_levelsobjectrequired

e.g., {'basic': 0, 'pro': 1, 'enterprise': 2}

Show child attributes

[key: string]integer

is_trialbooleanrequired

Indicates if the subscription is a trial

tenant_idstring | nullrequired

The tenant who owns the subscription

Show child attributes

Any of

string

null

actorstringrequired

who it is applied to, If end_user, then user_id must be set

user_idstring | nullrequired

The end user who has this subscription, if applicable

Show child attributes

Any of

string

null

plan_idstringrequired

Corresponding Stripe Price ID

plan_namestring | null

Plan name like Free, Starter, Pro, Enterprise

Show child attributes

Any of

string

null

stripe_subscription_statusstring | null

Stripe subscription status: active, trialing, incomplete, past_due, etc.

Show child attributes

Any of

string

null

trial_end_atstring | null

Trial end date if applicable

Show child attributes

Any of

string

null

Authorization

OAuth2PasswordBeareroauth2

Password Reset Request

POST

http://localhost:8000/api/v1/account/password_reset_request

Password Reset Request

curl -X POST 'http://localhost:8000/api/v1/account/password_reset_request' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com"
}'

const body = `{
  "email": "user@example.com"
}`;

const response = await fetch('http://localhost:8000/api/v1/account/password_reset_request', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "email": "user@example.com"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/account/password_reset_request',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "email": "user@example.com"
}

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

emailstring<email>required

Response

200OKBackend_PasswordResetResponseDto

Successful Response

Response fields application/json

messagestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Password Reset Confirm

POST

http://localhost:8000/api/v1/account/password_reset_confirmation

Password Reset Confirm

curl -X POST 'http://localhost:8000/api/v1/account/password_reset_confirmation?token=string&user_id=string' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "new_password": "string"
}'

const body = `{
  "new_password": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/account/password_reset_confirmation?token=string&user_id=string', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "new_password": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/account/password_reset_confirmation?token=string&user_id=string',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "new_password": "string"
}

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

new_passwordstringrequired

Parameters

tokenstringrequiredquery

The password reset token

user_idstringrequiredquery

The user ID associated with the token

tenant_idstring | nullquery

The tenant ID associated with the user, if applicable

Response

200OKBackend_PasswordResetResponseDto

Successful Response

Response fields application/json

messagestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Resend Activation Email

POST

http://localhost:8000/api/v1/account/resend_activation_email

Resend Activation Email

curl -X POST 'http://localhost:8000/api/v1/account/resend_activation_email' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com",
  "id": "string",
  "first_name": "string",
  "tenant_id": "string"
}'

const body = `{
  "email": "user@example.com",
  "id": "string",
  "first_name": "string",
  "tenant_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/account/resend_activation_email', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "email": "user@example.com",
  "id": "string",
  "first_name": "string",
  "tenant_id": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/account/resend_activation_email',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "email": "user@example.com",
  "id": "string",
  "first_name": "string",
  "tenant_id": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

emailstring<email>required

idstringrequired

first_namestringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Resend Activation Email Public

POST

http://localhost:8000/api/v1/account/resend_activation

Public resend of the account activation email, used by the account activation gate page for users whose accounts are inactive. Sending is refused for already-active accounts (InvalidOperationException).

Resend Activation Email Public

curl -X POST 'http://localhost:8000/api/v1/account/resend_activation' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com",
  "id": "string",
  "first_name": "string",
  "tenant_id": "string"
}'

const body = `{
  "email": "user@example.com",
  "id": "string",
  "first_name": "string",
  "tenant_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/account/resend_activation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "email": "user@example.com",
  "id": "string",
  "first_name": "string",
  "tenant_id": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/account/resend_activation',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "email": "user@example.com",
  "id": "string",
  "first_name": "string",
  "tenant_id": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

emailstring<email>required

idstringrequired

first_namestringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Activate Account

POST

http://localhost:8000/api/v1/account/activate

Activate Account

curl -X POST 'http://localhost:8000/api/v1/account/activate' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "token": "string"
}'

const body = `{
  "token": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/account/activate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "token": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/account/activate',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "token": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

tokenstringrequired

Parameters

tenant_idstring | nullquery

The tenant ID associated with the user, if applicable

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Change Email

PATCH

http://localhost:8000/api/v1/account/change_email_request

Change Email

curl -X PATCH 'http://localhost:8000/api/v1/account/change_email_request' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "new_email": "user@example.com"
}'

const body = `{
  "new_email": "user@example.com"
}`;

const response = await fetch('http://localhost:8000/api/v1/account/change_email_request', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "new_email": "user@example.com"
}'''

response = requests.patch(
    'http://localhost:8000/api/v1/account/change_email_request',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "new_email": "user@example.com"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

new_emailstring<email>required

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Change Email Confirmation

PATCH

http://localhost:8000/api/v1/account/change_email_confirmation

Change Email Confirmation

curl -X PATCH 'http://localhost:8000/api/v1/account/change_email_confirmation' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "token": "string"
}'

const body = `{
  "token": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/account/change_email_confirmation', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "token": "string"
}'''

response = requests.patch(
    'http://localhost:8000/api/v1/account/change_email_confirmation',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "token": "string"
}

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

tokenstringrequired

Response

200OKBackend_ChangeEmailResponseDto

Successful Response

Response fields application/json

messagestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Passkey Register Options

POST

http://localhost:8000/api/v1/account/passkey/register_options

Passkey Register Options

curl -X POST 'http://localhost:8000/api/v1/account/passkey/register_options' \
  -H 'Content-Type: application/json' \
  --data-raw '"user@example.com"'

const response = await fetch('http://localhost:8000/api/v1/account/passkey/register_options', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: '"user@example.com"',
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/account/passkey/register_options',
    data='"user@example.com"'.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

"user@example.com"

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

string<email>

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Passkey Register

POST

http://localhost:8000/api/v1/account/passkey/register

Passkey Register

curl -X POST 'http://localhost:8000/api/v1/account/passkey/register' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com",
  "credential": {}
}'

const body = `{
  "email": "user@example.com",
  "credential": {}
}`;

const response = await fetch('http://localhost:8000/api/v1/account/passkey/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "email": "user@example.com",
  "credential": {}
}'''

response = requests.post(
    'http://localhost:8000/api/v1/account/passkey/register',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "email": "user@example.com",
  "credential": {}
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

emailstring<email>required

credentialobjectrequired

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Passkey Login Options

POST

http://localhost:8000/api/v1/account/passkey/login_options

Passkey Login Options

curl -X POST 'http://localhost:8000/api/v1/account/passkey/login_options' \
  -H 'Content-Type: application/json' \
  --data-raw '"user@example.com"'

const response = await fetch('http://localhost:8000/api/v1/account/passkey/login_options', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: '"user@example.com"',
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/account/passkey/login_options',
    data='"user@example.com"'.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

"user@example.com"

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Response

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Passkey Login

POST

http://localhost:8000/api/v1/account/passkey/login

Passkey Login

curl -X POST 'http://localhost:8000/api/v1/account/passkey/login' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com",
  "credential": {}
}'

const body = `{
  "email": "user@example.com",
  "credential": {}
}`;

const response = await fetch('http://localhost:8000/api/v1/account/passkey/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "email": "user@example.com",
  "credential": {}
}'''

response = requests.post(
    'http://localhost:8000/api/v1/account/passkey/login',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "email": "user@example.com",
  "credential": {}
}

{
  "user": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url": "string",
    "is_active": true,
    "activated_at": "2024-01-15T09:30:00Z",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    },
    "user_code": "string"
  },
  "tenants": [
    {
      "id": "string",
      "name": "string",
      "subdomain": "string",
      "custom_domain": "string",
      "logo_url": "string",
      "role": {
        "id": "string",
        "name": "string",
        "description": "string",
        "permissions": [],
        "is_immutable": false,
        "created_at": "string",
        "updated_at": "string",
        "tenant_id": "string",
        "scope": "tenant_custom",
        "users_count": 0
      }
    }
  ],
  "requires_tenant_selection": true,
  "is_super_admin": true,
  "message": "Login successful",
  "token": "string",
  "refresh_token": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Response

200OKBackend_LoginResponseDto

Successful Response

Response fields application/json

Response after successful login with tenant selection info

userBackend_UserInfoDtorequired

User information returned after login

Show child attributes

idstringrequired

emailstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

user_codestring | null

Show child attributes

Any of

string

null

tenantsArray<Backend_TenantInfoDto>required

Show child attributes

Tenant information for selection

idstringrequired

namestringrequired

subdomainstring | null

Show child attributes

Any of

string

null

custom_domainstring | null

Show child attributes

Any of

string

null

logo_urlstring | null

Show child attributes

Any of

string

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

requires_tenant_selectionbooleanrequired

is_super_adminbooleanrequired

messagestringLogin successful

tokenstring | null

Show child attributes

Any of

string

null

refresh_tokenstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Has Passkeys

POST

http://localhost:8000/api/v1/account/passkey/has_passkeys

Has Passkeys

curl -X POST 'http://localhost:8000/api/v1/account/passkey/has_passkeys' \
  -H 'Content-Type: application/json' \
  --data-raw '"user@example.com"'

const response = await fetch('http://localhost:8000/api/v1/account/passkey/has_passkeys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: '"user@example.com"',
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/account/passkey/has_passkeys',
    data='"user@example.com"'.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

"user@example.com"

{
  "has_passkeys": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

string<email>

Response

200OKBackend_HasPasskeysDto

Successful Response

Response fields application/json

has_passkeysbooleanrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Email Magic Link Login

POST

http://localhost:8000/api/v1/account/email_magic_link_login

Email Magic Link Login

curl -X POST 'http://localhost:8000/api/v1/account/email_magic_link_login' \
  -H 'Content-Type: application/json' \
  --data-raw '"user@example.com"'

const response = await fetch('http://localhost:8000/api/v1/account/email_magic_link_login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: '"user@example.com"',
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/account/email_magic_link_login',
    data='"user@example.com"'.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

"user@example.com"

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Response

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Email Magic Link Validate

GET

http://localhost:8000/api/v1/account/email_magic_link_validate

Email Magic Link Validate

curl -X GET 'http://localhost:8000/api/v1/account/email_magic_link_validate?token=string&user_id=string'

const response = await fetch('http://localhost:8000/api/v1/account/email_magic_link_validate?token=string&user_id=string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8000/api/v1/account/email_magic_link_validate?token=string&user_id=string')
print(response.text)

{
  "user": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url": "string",
    "is_active": true,
    "activated_at": "2024-01-15T09:30:00Z",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    },
    "user_code": "string"
  },
  "tenants": [
    {
      "id": "string",
      "name": "string",
      "subdomain": "string",
      "custom_domain": "string",
      "logo_url": "string",
      "role": {
        "id": "string",
        "name": "string",
        "description": "string",
        "permissions": [],
        "is_immutable": false,
        "created_at": "string",
        "updated_at": "string",
        "tenant_id": "string",
        "scope": "tenant_custom",
        "users_count": 0
      }
    }
  ],
  "requires_tenant_selection": true,
  "is_super_admin": true,
  "message": "Login successful",
  "token": "string",
  "refresh_token": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

tokenstringrequiredquery

The magic link token

user_idstringrequiredquery

The user ID associated with the token

tenant_idstring | nullquery

The tenant ID associated with the user, if applicable

Response

200OKBackend_LoginResponseDto

Successful Response

Response fields application/json

Response after successful login with tenant selection info

userBackend_UserInfoDtorequired

User information returned after login

Show child attributes

idstringrequired

emailstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

user_codestring | null

Show child attributes

Any of

string

null

tenantsArray<Backend_TenantInfoDto>required

Show child attributes

Tenant information for selection

idstringrequired

namestringrequired

subdomainstring | null

Show child attributes

Any of

string

null

custom_domainstring | null

Show child attributes

Any of

string

null

logo_urlstring | null

Show child attributes

Any of

string

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

requires_tenant_selectionbooleanrequired

is_super_adminbooleanrequired

messagestringLogin successful

tokenstring | null

Show child attributes

Any of

string

null

refresh_tokenstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Backend / Manage Security

Manage Security — Backend

Get Registered Passkeys

GET

http://localhost:8000/api/v1/security/passkeys

Endpoint to retrieve registered passkeys for the current user.

Get Registered Passkeys

curl -X GET 'http://localhost:8000/api/v1/security/passkeys' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/security/passkeys', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/security/passkeys',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

[
  {
    "credential_id": "string",
    "public_key": "string",
    "sigin_count": 0,
    "transports": [],
    "created_at": "2024-01-15T09:30:00Z",
    "last_used_at": "2024-01-15T09:30:00Z"
  }
]

Response

200OKArray<Backend_RegisteredPasskeyCredentialsDto>

Successful Response

Response fields application/json

Array<Backend_RegisteredPasskeyCredentialsDto>

Show child attributes

credential_idstringrequired

public_keystringrequired

sigin_countintegerrequired

transportsArray<Backend_AuthenticatorTransport>usbnfcblesmart-cardinternalcablehybrid

created_atstring<date-time>required

last_used_atstring | null

Show child attributes

Any of

string<date-time>

null

Authorization

OAuth2PasswordBeareroauth2

Delete Registered Passkey

DELETE

http://localhost:8000/api/v1/security/passkeys/{credential_id}

Endpoint to delete a registered passkey for the current user.

Delete Registered Passkey

curl -X DELETE 'http://localhost:8000/api/v1/security/passkeys/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/security/passkeys/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8000/api/v1/security/passkeys/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

credential_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Dashboard

Dashboard — Backend

Get Dashboard Metrics

GET

http://localhost:8000/api/v1/dashboard

Get Dashboard Metrics

curl -X GET 'http://localhost:8000/api/v1/dashboard?filter=all' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/dashboard?filter=all', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/dashboard?filter=all',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "filter": "today",
  "joined_users": 0,
  "total_users": 0,
  "timeseries": [
    {
      "time_or_date": "string",
      "count": 0
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

filterstringtodaythis_weeklast_3_monthsallallquery

Response

200OKBackend_DashboardMetricsDto

Successful Response

Response fields application/json

filterstringtodaythis_weeklast_3_monthsallrequired

joined_usersintegerrequired

total_usersintegerrequired

timeseriesArray<Backend_TimeSeriesDto>required

Show child attributes

time_or_datestringrequired

countintegerrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Superadmin

Superadmin — Backend

Get Superadmin Dashboard

GET

http://localhost:8000/api/v1/superadmin/dashboard

Get superadmin dashboard with platform-wide metrics.

Get Superadmin Dashboard

curl -X GET 'http://localhost:8000/api/v1/superadmin/dashboard' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/superadmin/dashboard', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/superadmin/dashboard',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "tenants": {
    "total_tenants": 0,
    "active_tenants_30d": 0,
    "new_tenants_this_month": 0,
    "suspended_tenants": 0
  },
  "submissions": {
    "submissions_today": 0,
    "submissions_this_week": 0,
    "submissions_this_month": 0,
    "submissions_trend": [
      {}
    ]
  },
  "users": {
    "total_users": 0,
    "active_users_30d": 0,
    "new_users_this_month": 0
  },
  "subscriptions": {
    "mrr": 0,
    "active_subscriptions": 0,
    "trials_running": 0,
    "cancelled_this_month": 0,
    "plans_breakdown": {}
  },
  "infrastructure": {
    "celery_queue_size": 0,
    "redis_memory_mb": 0,
    "db_connections": 0,
    "storage_used_gb": 0,
    "webhook_failures": 0
  },
  "incidents": [
    {
      "id": "string",
      "type": "string",
      "severity": "critical",
      "message": "string",
      "tenant_id": "string",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "platform_health": {
    "status": "healthy",
    "api_uptime_seconds": 0,
    "last_incident_at": "2024-01-15T09:30:00Z",
    "active_incidents": 0
  },
  "submissions_trend": [
    {
      "date": "string",
      "count": 0
    }
  ],
  "tenant_growth_trend": [
    {
      "date": "string",
      "count": 0
    }
  ],
  "recent_tenant_activity": [
    {
      "tenant_id": "string",
      "tenant_name": "string",
      "subdomain": "string",
      "plan": "string",
      "users_count": 0,
      "surveys_count": 0,
      "submissions_count": 0,
      "last_activity_at": "2024-01-15T09:30:00Z",
      "status": "active"
    }
  ]
}

Response

200OKBackend_SuperadminDashboardDto

Successful Response

Response fields application/json

tenantsBackend_TenantMetricsDtorequired

Show child attributes

total_tenantsintegerrequired

active_tenants_30dintegerrequired

new_tenants_this_monthintegerrequired

suspended_tenantsintegerrequired

submissionsBackend_SubmissionMetricsDtorequired

Show child attributes

submissions_todayintegerrequired

submissions_this_weekintegerrequired

submissions_this_monthintegerrequired

submissions_trendArray<object>required

Show child attributes

[key: string]integer

usersBackend_UserMetricsDtorequired

Show child attributes

total_usersintegerrequired

active_users_30dintegerrequired

new_users_this_monthintegerrequired

subscriptionsBackend_SubscriptionMetricsDtorequired

Show child attributes

mrrnumberrequired

active_subscriptionsintegerrequired

trials_runningintegerrequired

cancelled_this_monthintegerrequired

plans_breakdownobjectrequired

Show child attributes

[key: string]integer

infrastructureBackend_InfrastructureMetricsDtorequired

Show child attributes

celery_queue_sizeintegerrequired

redis_memory_mbnumberrequired

db_connectionsintegerrequired

storage_used_gbnumberrequired

webhook_failuresintegerrequired

incidentsArray<Backend_IncidentDto>required

Show child attributes

idstringrequired

typestringrequired

severitystringcriticalwarninginforequired

messagestringrequired

tenant_idstring | nullrequired

Show child attributes

Any of

string

null

created_atstring<date-time>required

platform_healthBackend_PlatformHealthDtorequired

Show child attributes

statusstringhealthydegradeddownrequired

api_uptime_secondsnumberrequired

last_incident_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

active_incidentsintegerrequired

submissions_trendArray<Backend_TimeSeriesPointDto>required

Show child attributes

datestringrequired

countintegerrequired

tenant_growth_trendArray<Backend_TimeSeriesPointDto>required

Show child attributes

datestringrequired

countintegerrequired

recent_tenant_activityArray<Backend_TenantActivityDto>required

Show child attributes

tenant_idstringrequired

tenant_namestringrequired

subdomainstringrequired

planstringrequired

users_countintegerrequired

surveys_countintegerrequired

submissions_countintegerrequired

last_activity_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

statusstringactiveidlesuspendedemptyrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Users

Users — Backend

List Users

GET

http://localhost:8000/api/v1/users

List Users

curl -X GET 'http://localhost:8000/api/v1/users?skip=0&limit=10' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users?skip=0&limit=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/users?skip=0&limit=10',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "user@example.com",
      "gender": "male",
      "role_id": "string",
      "role_name": "string",
      "is_active": true,
      "member_active": true,
      "activated_at": "string",
      "image_url": "string",
      "user_code": "string",
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "permissions": [
        "string"
      ],
      "agreed_to_terms": false
    }
  ],
  "skip": 0,
  "limit": 0,
  "total": 0,
  "has_previous": true,
  "has_next": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

skipinteger0query

limitinteger10query

searchstring | nullquery

Response

200OKBackend_UserListDto

Successful Response

Response fields application/json

itemsArray<Backend_UserDto>required

Show child attributes

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

skipintegerrequired

limitintegerrequired

totalintegerrequired

has_previousbooleanrequired

has_nextbooleanrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Create User

POST

http://localhost:8000/api/v1/users

Create User

curl -X POST 'http://localhost:8000/api/v1/users' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "prefer_not_to_say",
  "tenant_id": "string",
  "role_id": "string",
  "password": "string",
  "sub_domain": "string",
  "agreed_to_terms": true
}'

const body = `{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "prefer_not_to_say",
  "tenant_id": "string",
  "role_id": "string",
  "password": "string",
  "sub_domain": "string",
  "agreed_to_terms": true
}`;

const response = await fetch('http://localhost:8000/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "prefer_not_to_say",
  "tenant_id": "string",
  "role_id": "string",
  "password": "string",
  "sub_domain": "string",
  "agreed_to_terms": true
}'''

response = requests.post(
    'http://localhost:8000/api/v1/users',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "prefer_not_to_say",
  "tenant_id": "string",
  "role_id": "string",
  "password": "string",
  "sub_domain": "string",
  "agreed_to_terms": true
}

{
  "id": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gender | nullprefer_not_to_say

Show child attributes

Any of

Backend_Gendermalefemaleotherprefer_not_to_say

null

tenant_idstring | null

Show child attributes

Any of

string

null

role_idstring | null

Show child attributes

Any of

string

null

passwordstringrequired

sub_domainstring | null

Show child attributes

Any of

string

null

agreed_to_termsbooleantrue

Response

201CreatedBackend_CreateUserResponseDto

Successful Response

Response fields application/json

idstringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Search User By Email

GET

http://localhost:8000/api/v1/users/search/by-email

Search for a user by their email address within the current tenant context. Returns user details if found, useful for workspace member invitations.

Search User By Email

curl -X GET 'http://localhost:8000/api/v1/users/search/by-email?email=string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/search/by-email?email=string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/users/search/by-email?email=string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "role_id": "string",
  "role_name": "string",
  "is_active": true,
  "member_active": true,
  "activated_at": "string",
  "image_url": "string",
  "user_code": "string",
  "created_at": "string",
  "updated_at": "string",
  "tenant_id": "string",
  "permissions": [
    "string"
  ],
  "agreed_to_terms": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

emailstringrequiredquery

Response

200OKBackend_UserDto

Successful Response

Response fields application/json

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Search Users With Roles

GET

http://localhost:8000/api/v1/users/search/with-roles

Search users with role filtering.

Useful for form access management where you need to find Field Supervisors or Enumerators in the same tenant.

SECURITY: Form Builders and Field Supervisors can only search Field Supervisors and Enumerators. Admins and Survey Managers can search all users.

role_ids: Comma-separated list of role UUIDs (e.g., "uuid1,uuid2")
search: Search by first_name, last_name, email, or user_code

Search Users With Roles

curl -X GET 'http://localhost:8000/api/v1/users/search/with-roles?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/search/with-roles?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/users/search/with-roles?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "user@example.com",
      "gender": "male",
      "role_id": "string",
      "role_name": "string",
      "is_active": true,
      "member_active": true,
      "activated_at": "string",
      "image_url": "string",
      "user_code": "string",
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "permissions": [
        "string"
      ],
      "agreed_to_terms": false
    }
  ],
  "skip": 0,
  "limit": 0,
  "total": 0,
  "has_previous": true,
  "has_next": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

role_idsstring | nullquery

Comma-separated list of role IDs to filter by

searchstring | nullquery

Search by name, email, or user_code

Response

200OKBackend_UserListDto

Successful Response

Response fields application/json

itemsArray<Backend_UserDto>required

Show child attributes

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

skipintegerrequired

limitintegerrequired

totalintegerrequired

has_previousbooleanrequired

has_nextbooleanrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get Users Bulk

POST

http://localhost:8000/api/v1/users/bulk

Fetch multiple users by their IDs in bulk, scoped to the current tenant. Prevents cross-tenant user enumeration.

Get Users Bulk

curl -X POST 'http://localhost:8000/api/v1/users/bulk' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "user_ids": [
    "string"
  ]
}'

const body = `{
  "user_ids": [
    "string"
  ]
}`;

const response = await fetch('http://localhost:8000/api/v1/users/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "user_ids": [
    "string"
  ]
}'''

response = requests.post(
    'http://localhost:8000/api/v1/users/bulk',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "user_ids": [
    "string"
  ]
}

[
  {
    "id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "gender": "male",
    "role_id": "string",
    "role_name": "string",
    "is_active": true,
    "member_active": true,
    "activated_at": "string",
    "image_url": "string",
    "user_code": "string",
    "created_at": "string",
    "updated_at": "string",
    "tenant_id": "string",
    "permissions": [
      "string"
    ],
    "agreed_to_terms": false
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

user_idsArray<string>required

Response

200OKArray<Backend_UserDto>

Successful Response

Response fields application/json

Array<Backend_UserDto>

Show child attributes

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Provision User

POST

http://localhost:8000/api/v1/users/provision

Provision a user to the current tenant.

CASE A — New user: Creates the user and adds them to the tenant with the selected role. CASE B — Existing user: Adds the existing user to the tenant with the selected role. CASE C — Already a member: Returns a friendly message without creating duplicates.

Role selection is mandatory in all cases.

Provision User

curl -X POST 'http://localhost:8000/api/v1/users/provision' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "email": "user@example.com",
  "role_id": "string",
  "password": "string",
  "first_name": "string",
  "last_name": "string",
  "gender": "male"
}'

const body = `{
  "email": "user@example.com",
  "role_id": "string",
  "password": "string",
  "first_name": "string",
  "last_name": "string",
  "gender": "male"
}`;

const response = await fetch('http://localhost:8000/api/v1/users/provision', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "email": "user@example.com",
  "role_id": "string",
  "password": "string",
  "first_name": "string",
  "last_name": "string",
  "gender": "male"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/users/provision',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "email": "user@example.com",
  "role_id": "string",
  "password": "string",
  "first_name": "string",
  "last_name": "string",
  "gender": "male"
}

{
  "id": "string",
  "status": "string",
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

DTO for provisioning a user to a tenant (create or invite)

emailstring<email>required

role_idstringrequired

passwordstring | null

Show child attributes

Any of

string

null

first_namestring | null

Show child attributes

Any of

string

null

last_namestring | null

Show child attributes

Any of

string

null

genderBackend_Gender | null

Show child attributes

Any of

Backend_Gendermalefemaleotherprefer_not_to_say

null

Response

201CreatedBackend_ProvisionUserResponseDto

Successful Response

Response fields application/json

Response DTO for user provisioning

idstringrequired

statusstringrequired

messagestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get Available Roles

GET

http://localhost:8000/api/v1/users/available-roles

Get Available Roles

curl -X GET 'http://localhost:8000/api/v1/users/available-roles' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/available-roles', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/users/available-roles',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

[
  {}
]

Response

200OKArray<object>

Successful Response

Response fields application/json

Array<object>

Authorization

OAuth2PasswordBeareroauth2

Count Users

GET

http://localhost:8000/api/v1/users/count

Count users in the current tenant, optionally filtered by account active status and/or role name (e.g. "Enumerator"). Super admins count across all tenants when no role filter is applied.

Count Users

curl -X GET 'http://localhost:8000/api/v1/users/count' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/count', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/users/count',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "total": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

is_activeboolean | nullquery

role_namestring | nullquery

Response

200OKBackend_UserCountDto

Successful Response

Response fields application/json

totalintegerrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get User

GET

http://localhost:8000/api/v1/users/{user_id}

Get a single user by ID, scoped to the current tenant. Non-super-admin users can only retrieve users belonging to their active tenant.

Get User

curl -X GET 'http://localhost:8000/api/v1/users/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/users/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "role_id": "string",
  "role_name": "string",
  "is_active": true,
  "member_active": true,
  "activated_at": "string",
  "image_url": "string",
  "user_code": "string",
  "created_at": "string",
  "updated_at": "string",
  "tenant_id": "string",
  "permissions": [
    "string"
  ],
  "agreed_to_terms": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

user_idstringrequiredpath

Response

200OKBackend_UserDto

Successful Response

Response fields application/json

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update User

PUT

http://localhost:8000/api/v1/users/{user_id}

Update User

curl -X PUT 'http://localhost:8000/api/v1/users/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "image_url": "string",
  "role_id": "string",
  "is_active": true,
  "activated_at": "2024-01-15T09:30:00Z",
  "tenant_id": "string",
  "password": "string"
}'

const body = `{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "image_url": "string",
  "role_id": "string",
  "is_active": true,
  "activated_at": "2024-01-15T09:30:00Z",
  "tenant_id": "string",
  "password": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/users/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "image_url": "string",
  "role_id": "string",
  "is_active": true,
  "activated_at": "2024-01-15T09:30:00Z",
  "tenant_id": "string",
  "password": "string"
}'''

response = requests.put(
    'http://localhost:8000/api/v1/users/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "image_url": "string",
  "role_id": "string",
  "is_active": true,
  "activated_at": "2024-01-15T09:30:00Z",
  "tenant_id": "string",
  "password": "string"
}

{
  "id": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "role_id": "string",
  "role_name": "string",
  "is_active": true,
  "member_active": true,
  "activated_at": "string",
  "image_url": "string",
  "user_code": "string",
  "created_at": "string",
  "updated_at": "string",
  "tenant_id": "string",
  "permissions": [
    "string"
  ],
  "agreed_to_terms": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

first_namestring | null

Show child attributes

Any of

string

null

last_namestring | null

Show child attributes

Any of

string

null

emailstring | null

Show child attributes

Any of

string<email>

null

genderBackend_Gender | null

Show child attributes

Any of

Backend_Gendermalefemaleotherprefer_not_to_say

null

image_urlstring | null

Show child attributes

Any of

string

null

role_idstring | null

Show child attributes

Any of

string

null

is_activeboolean | null

Show child attributes

Any of

boolean

null

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

tenant_idstring | null

Show child attributes

Any of

string

null

passwordstring | null

Show child attributes

Any of

string

null

Parameters

user_idstringrequiredpath

Response

200OKBackend_UserDto

Successful Response

Response fields application/json

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Delete User

DELETE

http://localhost:8000/api/v1/users/{user_id}

Delete User

curl -X DELETE 'http://localhost:8000/api/v1/users/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8000/api/v1/users/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

user_idstringrequiredpath

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get Profile Image

GET

http://localhost:8000/api/v1/users/profile/{image_key}

Get Profile Image

curl -X GET 'http://localhost:8000/api/v1/users/profile/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/profile/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/users/profile/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "image_url": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

image_keystringrequiredpath

Response

200OKBackend_UserProfileImageUpdateDto

Successful Response

Response fields application/json

image_urlstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update User Tenant Access

PATCH

http://localhost:8000/api/v1/users/{user_id}/tenant-access

Activate or deactivate a user's membership in the active tenant.

Per-tenant activation: deactivating a membership in one tenant does NOT affect the user's access or login ability in other tenants, nor does it disable the global account (users.is_active). The active tenant is resolved from the X-Tenant-ID header, falling back to the actor's primary tenant.

Update User Tenant Access

curl -X PATCH 'http://localhost:8000/api/v1/users/string/tenant-access' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "is_active": true
}'

const body = `{
  "is_active": true
}`;

const response = await fetch('http://localhost:8000/api/v1/users/string/tenant-access', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "is_active": true
}'''

response = requests.patch(
    'http://localhost:8000/api/v1/users/string/tenant-access',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "is_active": true
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

DTO for updating a user's per-tenant access (activate/deactivate in the active tenant)

is_activebooleanrequired

Parameters

user_idstringrequiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update Profile Picture

PUT

http://localhost:8000/api/v1/users/{user_id}/update_profile_picture

Update Profile Picture

curl -X PUT 'http://localhost:8000/api/v1/users/string/update_profile_picture' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const form = new FormData();
const response = await fetch('http://localhost:8000/api/v1/users/string/update_profile_picture', {
  method: 'PUT',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
    ]
    response = requests.request('PUT', 'http://localhost:8000/api/v1/users/string/update_profile_picture', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "file": "<binary>"
}

{
  "image_url": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

multipart/form-data

filestring<binary>required

Parameters

user_idstringrequiredpath

Response

202AcceptedBackend_UserProfileImageUpdateDto

Successful Response

Response fields application/json

image_urlstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Delete Profile Picture

DELETE

http://localhost:8000/api/v1/users/{user_id}/delete_profile_picture

Delete Profile Picture

curl -X DELETE 'http://localhost:8000/api/v1/users/string/delete_profile_picture' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/string/delete_profile_picture', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8000/api/v1/users/string/delete_profile_picture',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "image_url": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

user_idstringrequiredpath

Response

202AcceptedBackend_UserProfileImageUpdateDto

Successful Response

Response fields application/json

image_urlstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Patch User

PATCH

http://localhost:8000/api/v1/users/{user_id}/assign_role

Patch User

curl -X PATCH 'http://localhost:8000/api/v1/users/string/assign_role' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "role_id": "string"
}'

const body = `{
  "role_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/users/string/assign_role', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "role_id": "string"
}'''

response = requests.patch(
    'http://localhost:8000/api/v1/users/string/assign_role',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "role_id": "string"
}

{
  "id": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "role_id": "string",
  "role_name": "string",
  "is_active": true,
  "member_active": true,
  "activated_at": "string",
  "image_url": "string",
  "user_code": "string",
  "created_at": "string",
  "updated_at": "string",
  "tenant_id": "string",
  "permissions": [
    "string"
  ],
  "agreed_to_terms": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

role_idstringrequired

Parameters

user_idstringrequiredpath

Response

202AcceptedBackend_UserDto

Successful Response

Response fields application/json

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Remove User Role

PATCH

http://localhost:8000/api/v1/users/{user_id}/remove_role

Remove User Role

curl -X PATCH 'http://localhost:8000/api/v1/users/string/remove_role' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "role_id": "string"
}'

const body = `{
  "role_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/users/string/remove_role', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "role_id": "string"
}'''

response = requests.patch(
    'http://localhost:8000/api/v1/users/string/remove_role',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "role_id": "string"
}

{
  "id": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "role_id": "string",
  "role_name": "string",
  "is_active": true,
  "member_active": true,
  "activated_at": "string",
  "image_url": "string",
  "user_code": "string",
  "created_at": "string",
  "updated_at": "string",
  "tenant_id": "string",
  "permissions": [
    "string"
  ],
  "agreed_to_terms": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

role_idstringrequired

Parameters

user_idstringrequiredpath

Response

202AcceptedBackend_UserDto

Successful Response

Response fields application/json

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / User Tenants

User Tenants — Backend

Get My Tenants

GET

http://localhost:8000/api/v1/users/me/tenants

Get all tenants for the currently authenticated user. This endpoint is accessible to all authenticated users.

Get My Tenants

curl -X GET 'http://localhost:8000/api/v1/users/me/tenants?skip=0&limit=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/me/tenants?skip=0&limit=100', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/users/me/tenants?skip=0&limit=100',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "user_id": "string",
      "tenant_id": "string",
      "tenant_name": "string",
      "role_id": "string",
      "role_name": "string",
      "permissions": [],
      "is_primary": true,
      "is_active": true,
      "joined_at": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 10,
  "has_next": false,
  "has_previous": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

skipinteger0query

limitinteger100query

Response

200OKBackend_UserTenantListDto

Successful Response

Response fields application/json

DTO for listing user tenants

itemsArray<Backend_UserTenantDto>required

Show child attributes

DTO for user-tenant relationship

idstringrequired

user_idstringrequired

tenant_idstringrequired

tenant_namestring | null

Show child attributes

Any of

string

null

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

permissionsArray<string>

is_primarybooleanrequired

is_activebooleantrue

joined_atstringrequired

totalintegerrequired

skipinteger0

limitinteger10

has_nextbooleanfalse

has_previousbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get User Tenants

GET

http://localhost:8000/api/v1/users/{user_id}/tenants

Get all tenants for a user. Users can view their own tenants. Platform admins can view any user's tenants. Tenant admins can only view memberships for their own authorized tenant(s).

Get User Tenants

curl -X GET 'http://localhost:8000/api/v1/users/string/tenants?skip=0&limit=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/string/tenants?skip=0&limit=100', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/users/string/tenants?skip=0&limit=100',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "user_id": "string",
      "tenant_id": "string",
      "tenant_name": "string",
      "role_id": "string",
      "role_name": "string",
      "permissions": [],
      "is_primary": true,
      "is_active": true,
      "joined_at": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 10,
  "has_next": false,
  "has_previous": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

user_idstringrequiredpath

skipinteger0query

limitinteger100query

Response

200OKBackend_UserTenantListDto

Successful Response

Response fields application/json

DTO for listing user tenants

itemsArray<Backend_UserTenantDto>required

Show child attributes

DTO for user-tenant relationship

idstringrequired

user_idstringrequired

tenant_idstringrequired

tenant_namestring | null

Show child attributes

Any of

string

null

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

permissionsArray<string>

is_primarybooleanrequired

is_activebooleantrue

joined_atstringrequired

totalintegerrequired

skipinteger0

limitinteger10

has_nextbooleanfalse

has_previousbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Add User To Tenant

POST

http://localhost:8000/api/v1/users/{user_id}/tenants

Add a user to a tenant. Only users with USER_READ_AND_WRITE_ONLY permission can add users to tenants.

Add User To Tenant

curl -X POST 'http://localhost:8000/api/v1/users/string/tenants' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "user_id": "string",
  "tenant_id": "string",
  "role_id": "string",
  "is_primary": false,
  "is_active": true
}'

const body = `{
  "user_id": "string",
  "tenant_id": "string",
  "role_id": "string",
  "is_primary": false,
  "is_active": true
}`;

const response = await fetch('http://localhost:8000/api/v1/users/string/tenants', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "user_id": "string",
  "tenant_id": "string",
  "role_id": "string",
  "is_primary": false,
  "is_active": true
}'''

response = requests.post(
    'http://localhost:8000/api/v1/users/string/tenants',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "user_id": "string",
  "tenant_id": "string",
  "role_id": "string",
  "is_primary": false,
  "is_active": true
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

DTO for creating user-tenant relationship

user_idstringrequired

tenant_idstringrequired

role_idstring | null

Show child attributes

Any of

string

null

is_primarybooleanfalse

is_activebooleantrue

Parameters

user_idstringrequiredpath

Response

201Createdobject

Successful Response

Response fields application/json

object

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update User Tenant

PUT

http://localhost:8000/api/v1/users/{user_id}/tenants/{user_tenant_id}

Update a user-tenant relationship (change role or primary status). Only users with USER_READ_AND_WRITE_ONLY permission can update.

Update User Tenant

curl -X PUT 'http://localhost:8000/api/v1/users/string/tenants/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "role_id": "string",
  "is_primary": true,
  "is_active": true
}'

const body = `{
  "role_id": "string",
  "is_primary": true,
  "is_active": true
}`;

const response = await fetch('http://localhost:8000/api/v1/users/string/tenants/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "role_id": "string",
  "is_primary": true,
  "is_active": true
}'''

response = requests.put(
    'http://localhost:8000/api/v1/users/string/tenants/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "role_id": "string",
  "is_primary": true,
  "is_active": true
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

DTO for updating user-tenant relationship

role_idstring | null

Show child attributes

Any of

string

null

is_primaryboolean | null

Show child attributes

Any of

boolean

null

is_activeboolean | null

Show child attributes

Any of

boolean

null

Parameters

user_idstringrequiredpath

user_tenant_idstringrequiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Remove User From Tenant

DELETE

http://localhost:8000/api/v1/users/{user_id}/tenants/{user_tenant_id}

Remove a user from a tenant. Only users with USER_DELETE_ONLY permission can remove users from tenants.

Remove User From Tenant

curl -X DELETE 'http://localhost:8000/api/v1/users/string/tenants/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/string/tenants/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8000/api/v1/users/string/tenants/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

user_idstringrequiredpath

user_tenant_idstringrequiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Set Primary Tenant

POST

http://localhost:8000/api/v1/users/{user_id}/tenants/set-primary

Set a tenant as the primary tenant for a user. Users can set their own primary tenant. Admins can set for any user.

Set Primary Tenant

curl -X POST 'http://localhost:8000/api/v1/users/string/tenants/set-primary' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "tenant_id": "string"
}'

const body = `{
  "tenant_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/users/string/tenants/set-primary', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "tenant_id": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/users/string/tenants/set-primary',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "tenant_id": "string"
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

DTO for setting primary tenant

tenant_idstringrequired

Parameters

user_idstringrequiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get Primary Tenant

GET

http://localhost:8000/api/v1/users/{user_id}/tenants/primary

Get the primary tenant for a user. Users can view their own primary tenant. Admins can view for any user.

Get Primary Tenant

curl -X GET 'http://localhost:8000/api/v1/users/string/tenants/primary' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/string/tenants/primary', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/users/string/tenants/primary',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

user_idstringrequiredpath

Response

200OKobject | null

Successful Response

Response fields application/json

Any of

object

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Switch Primary Tenant

POST

http://localhost:8000/api/v1/users/me/tenants/switch

Switch the primary tenant for the currently authenticated user. The user must already be a member of the tenant.

Switch Primary Tenant

curl -X POST 'http://localhost:8000/api/v1/users/me/tenants/switch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "tenant_id": "string"
}'

const body = `{
  "tenant_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/users/me/tenants/switch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "tenant_id": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/users/me/tenants/switch',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "tenant_id": "string"
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

DTO for setting primary tenant

tenant_idstringrequired

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Bulk Upload Users

POST

http://localhost:8000/api/v1/users/bulk-upload

Bulk upload users to a tenant from CSV or Excel file.

Expected CSV/Excel columns:

email (required)
first_name or firstName (required)
last_name or lastName (optional)
gender (optional: male, female, other, prefer_not_to_say)
role_name or roleName (optional: e.g., 'Admin', 'User', 'Manager')

For existing users: They will be added to the tenant. For new users: They will be created and added to the tenant.

Note: Use role_name instead of role_id for easier file preparation. Get available role names from GET /api/v1/users/available-roles endpoint.

Bulk Upload Users

curl -X POST 'http://localhost:8000/api/v1/users/bulk-upload' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'tenant_id=string' \
  --form-string 'default_role_id=string' \
  --form-string 'default_role_name=string' \
  --form-string 'send_invitation=true'

const form = new FormData();
form.append('tenant_id', 'string');
form.append('default_role_id', 'string');
form.append('default_role_name', 'string');
form.append('send_invitation', 'true');
const response = await fetch('http://localhost:8000/api/v1/users/bulk-upload', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('tenant_id', (None, 'string')),
        ('default_role_id', (None, 'string')),
        ('default_role_name', (None, 'string')),
        ('send_invitation', (None, 'true')),
    ]
    response = requests.request('POST', 'http://localhost:8000/api/v1/users/bulk-upload', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "tenant_id": "string",
  "default_role_id": "string",
  "default_role_name": "string",
  "send_invitation": true,
  "file": "<binary>"
}

{
  "total": 0,
  "success": 0,
  "failed": 0,
  "results": [
    {
      "email": "string",
      "success": true,
      "user_id": "string",
      "message": "string",
      "error": "string"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

multipart/form-data

tenant_idstringrequired

Tenant ID to add users to

default_role_idstring | null

Default role ID for new users

Show child attributes

Any of

string

null

default_role_namestring | null

Default role name for new users (e.g., 'Admin', 'User')

Show child attributes

Any of

string

null

send_invitationbooleantrue

Whether to send invitation emails

filestring<binary>required

CSV or Excel file with user data

Response

201CreatedBackend_BulkUserUploadResponseDto

Successful Response

Response fields application/json

DTO for bulk user upload response

totalintegerrequired

successintegerrequired

failedintegerrequired

resultsArray<Backend_BulkUserUploadResultDto>required

Show child attributes

DTO for individual user upload result

emailstringrequired

successbooleanrequired

user_idstring | null

Show child attributes

Any of

string

null

messagestringrequired

errorstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Roles

Roles — Backend

List Roles

GET

http://localhost:8000/api/v1/roles

List Roles

curl -X GET 'http://localhost:8000/api/v1/roles?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/roles?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/roles?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    }
  ],
  "skip": 0,
  "limit": 0,
  "total": 0,
  "has_previous": true,
  "has_next": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

searchstring | nullquery

Search by role name

Response

200OKBackend_RoleListDto

Successful Response

Response fields application/json

itemsArray<Backend_RoleDto>required

Show child attributes

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

skipintegerrequired

limitintegerrequired

totalintegerrequired

has_previousbooleanrequired

has_nextbooleanrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Create Role

POST

http://localhost:8000/api/v1/roles

Create Role

curl -X POST 'http://localhost:8000/api/v1/roles' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "tenant_id": "string",
  "permissions": [
    "super:admin"
  ],
  "is_immutable": false
}'

const body = `{
  "name": "string",
  "description": "string",
  "tenant_id": "string",
  "permissions": [
    "super:admin"
  ],
  "is_immutable": false
}`;

const response = await fetch('http://localhost:8000/api/v1/roles', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "tenant_id": "string",
  "permissions": [
    "super:admin"
  ],
  "is_immutable": false
}'''

response = requests.post(
    'http://localhost:8000/api/v1/roles',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "tenant_id": "string",
  "permissions": [
    "super:admin"
  ],
  "is_immutable": false
}

{
  "id": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

is_immutablebooleanfalse

Response

201CreatedBackend_CreateRoleResponseDto

Successful Response

Response fields application/json

idstringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Search Role By Name

GET

http://localhost:8000/api/v1/roles/search_by_name

Search Role By Name

curl -X GET 'http://localhost:8000/api/v1/roles/search_by_name?name=string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/roles/search_by_name?name=string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/roles/search_by_name?name=string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "permissions": [],
    "is_immutable": false,
    "created_at": "string",
    "updated_at": "string",
    "tenant_id": "string",
    "scope": "tenant_custom",
    "users_count": 0
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

namestringrequiredquery

Response

200OKArray<Backend_RoleDto>

Successful Response

Response fields application/json

Array<Backend_RoleDto>

Show child attributes

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update Role Permissions

PATCH

http://localhost:8000/api/v1/roles/{role_id}/permissions

Update role permissions only (for inline editing in Role Details).

Update Role Permissions

curl -X PATCH 'http://localhost:8000/api/v1/roles/string/permissions' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "permissions": [
    "super:admin"
  ]
}'

const body = `{
  "permissions": [
    "super:admin"
  ]
}`;

const response = await fetch('http://localhost:8000/api/v1/roles/string/permissions', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "permissions": [
    "super:admin"
  ]
}'''

response = requests.patch(
    'http://localhost:8000/api/v1/roles/string/permissions',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "permissions": [
    "super:admin"
  ]
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

Parameters

role_idstringrequiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get Role

GET

http://localhost:8000/api/v1/roles/{role_id}

Get Role

curl -X GET 'http://localhost:8000/api/v1/roles/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/roles/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/roles/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "name": "string",
  "description": "string",
  "permissions": [],
  "is_immutable": false,
  "created_at": "string",
  "updated_at": "string",
  "tenant_id": "string",
  "scope": "tenant_custom",
  "users_count": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

role_idstringrequiredpath

Response

200OKBackend_RoleDto

Successful Response

Response fields application/json

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update Role

PUT

http://localhost:8000/api/v1/roles/{role_id}

Update Role

curl -X PUT 'http://localhost:8000/api/v1/roles/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "tenant_id": "string",
  "permissions": [
    "super:admin"
  ],
  "is_immutable": false
}'

const body = `{
  "name": "string",
  "description": "string",
  "tenant_id": "string",
  "permissions": [
    "super:admin"
  ],
  "is_immutable": false
}`;

const response = await fetch('http://localhost:8000/api/v1/roles/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "tenant_id": "string",
  "permissions": [
    "super:admin"
  ],
  "is_immutable": false
}'''

response = requests.put(
    'http://localhost:8000/api/v1/roles/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "tenant_id": "string",
  "permissions": [
    "super:admin"
  ],
  "is_immutable": false
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

is_immutablebooleanfalse

Parameters

role_idstringrequiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Delete Role

DELETE

http://localhost:8000/api/v1/roles/{role_id}

Deletes a role if it is not assigned to any users.

Delete Role

curl -X DELETE 'http://localhost:8000/api/v1/roles/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/roles/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8000/api/v1/roles/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

role_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Sync Admin Permissions

POST

http://localhost:8000/api/v1/roles/sync-admin-permissions

Sync ADMIN role permissions with the latest from seeder_utils. Use this after adding new permissions.

Sync Admin Permissions

curl -X POST 'http://localhost:8000/api/v1/roles/sync-admin-permissions' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/roles/sync-admin-permissions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/roles/sync-admin-permissions',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Authorization

OAuth2PasswordBeareroauth2

Sync User Permissions

POST

http://localhost:8000/api/v1/roles/sync-user-permissions

Sync USER role permissions with the latest from seeder_utils. Use this after adding new permissions.

Sync User Permissions

curl -X POST 'http://localhost:8000/api/v1/roles/sync-user-permissions' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/roles/sync-user-permissions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/roles/sync-user-permissions',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Authorization

OAuth2PasswordBeareroauth2

Get Grouped Permissions

GET

http://localhost:8000/api/v1/roles/grouped-permissions

Get permissions grouped by category for enterprise permission management UI

Get Grouped Permissions

curl -X GET 'http://localhost:8000/api/v1/roles/grouped-permissions' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/roles/grouped-permissions', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/roles/grouped-permissions',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

[
  {
    "category": "User Management",
    "permissions": [
      {
        "name": "string",
        "display_name": "string",
        "description": "string",
        "category": "User Management",
        "danger_level": "low"
      }
    ]
  }
]

Response

200OKArray<Backend_PermissionGroupedDto>

Successful Response

Response fields application/json

Array<Backend_PermissionGroupedDto>

Show child attributes

categoryBackend_PermissionCategoryUser ManagementRole ManagementSurvey ManagementForm ManagementResponse ManagementWorkspace ManagementAnalyticsReportingExportNotificationMediaSystemBillingFeature FlagsComplianceAuditPlatformrequired

Logical grouping of permissions.

permissionsArray<Backend_PermissionDto>required

Show child attributes

namestringrequired

display_namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

categoryBackend_PermissionCategory | null

Show child attributes

Any of

Logical grouping of permissions.

Backend_PermissionCategoryUser ManagementRole ManagementSurvey ManagementForm ManagementResponse ManagementWorkspace ManagementAnalyticsReportingExportNotificationMediaSystemBillingFeature FlagsComplianceAuditPlatform

null

danger_levelBackend_PermissionDangerLevellowmediumhighdangerouslow

Categorizes permissions by potential system impact.

Authorization

OAuth2PasswordBeareroauth2

Get Role Stats

GET

http://localhost:8000/api/v1/roles/{role_id}/stats

Get role statistics including assigned users count

Get Role Stats

curl -X GET 'http://localhost:8000/api/v1/roles/string/stats' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/roles/string/stats', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/roles/string/stats',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

role_idstringrequiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get Role Users

GET

http://localhost:8000/api/v1/roles/{role_id}/users

List users assigned to a role (checks both users.role_id and user_tenants.role_id).

Get Role Users

curl -X GET 'http://localhost:8000/api/v1/roles/string/users?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/roles/string/users?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/roles/string/users?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "user@example.com",
      "gender": "male",
      "role_id": "string",
      "role_name": "string",
      "is_active": true,
      "member_active": true,
      "activated_at": "string",
      "image_url": "string",
      "user_code": "string",
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "permissions": [
        "string"
      ],
      "agreed_to_terms": false
    }
  ],
  "skip": 0,
  "limit": 0,
  "total": 0,
  "has_previous": true,
  "has_next": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

role_idstringrequiredpath

skipinteger>= 00query

limitinteger[1, 100]20query

Response

200OKBackend_UserListDto

Successful Response

Response fields application/json

itemsArray<Backend_UserDto>required

Show child attributes

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

skipintegerrequired

limitintegerrequired

totalintegerrequired

has_previousbooleanrequired

has_nextbooleanrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Permissions

Permissions — Backend

Get Permissions

GET

http://localhost:8000/api/v1/permissions

Get Permissions

curl -X GET 'http://localhost:8000/api/v1/permissions' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/permissions', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/permissions',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

[
  {
    "name": "string",
    "display_name": "string",
    "description": "string",
    "category": "User Management",
    "danger_level": "low"
  }
]

Response

200OKArray<Backend_PermissionDto>

Successful Response

Response fields application/json

Array<Backend_PermissionDto>

Show child attributes

namestringrequired

display_namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

categoryBackend_PermissionCategory | null

Show child attributes

Any of

Logical grouping of permissions.

null

danger_levelBackend_PermissionDangerLevellowmediumhighdangerouslow

Categorizes permissions by potential system impact.

Authorization

OAuth2PasswordBeareroauth2

Backend / Stripe - Products

Stripe - Products — Backend

List Products

GET

http://localhost:8000/api/v1/products

List Products

curl -X GET 'http://localhost:8000/api/v1/products' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/products', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/products',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "products": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "tax_code": "string",
      "active": true
    }
  ],
  "has_more": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

activeboolean | nullquery

Filter active products. None returns all.

Response

200OKBackend_ProductListDto

Successful Response

Response fields application/json

productsArray<Backend_ProductDto>required

Show child attributes

idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

tax_codestring | null

Show child attributes

Any of

string

null

activebooleanrequired

has_morebooleanrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Create a Product

POST

http://localhost:8000/api/v1/products

Create a Product

curl -X POST 'http://localhost:8000/api/v1/products' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "tax_code": "string",
  "active": true
}'

const body = `{
  "name": "string",
  "description": "string",
  "tax_code": "string",
  "active": true
}`;

const response = await fetch('http://localhost:8000/api/v1/products', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "tax_code": "string",
  "active": true
}'''

response = requests.post(
    'http://localhost:8000/api/v1/products',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "tax_code": "string",
  "active": true
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

tax_codestring | null

Show child attributes

Any of

string

null

activebooleantrue

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get Product by ID

GET

http://localhost:8000/api/v1/products/{product_id}

Get Product by ID

curl -X GET 'http://localhost:8000/api/v1/products/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/products/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/products/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "name": "string",
  "description": "string",
  "tax_code": "string",
  "active": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

product_idstringrequiredpath

Response

200OKBackend_ProductDto

Successful Response

Response fields application/json

idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

tax_codestring | null

Show child attributes

Any of

string

null

activebooleanrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Delete a Product

DELETE

http://localhost:8000/api/v1/products/{product_id}

Delete a Product

curl -X DELETE 'http://localhost:8000/api/v1/products/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/products/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8000/api/v1/products/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

product_idstringrequiredpath

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update a Product

PATCH

http://localhost:8000/api/v1/products/{product_id}

Update a Product

curl -X PATCH 'http://localhost:8000/api/v1/products/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "tax_code": "string",
  "active": true
}'

const body = `{
  "name": "string",
  "description": "string",
  "tax_code": "string",
  "active": true
}`;

const response = await fetch('http://localhost:8000/api/v1/products/string', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "tax_code": "string",
  "active": true
}'''

response = requests.patch(
    'http://localhost:8000/api/v1/products/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "tax_code": "string",
  "active": true
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

tax_codestring | null

Show child attributes

Any of

string

null

activebooleantrue

Parameters

product_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Stripe - Pricing

Stripe - Pricing — Backend

Get Pricing List

GET

http://localhost:8000/api/v1/prices

Get Pricing List

curl -X GET 'http://localhost:8000/api/v1/prices' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/prices', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/prices',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "pricings": [
    {
      "id": "string",
      "currency": "string",
      "unit_amount": 0,
      "product": "string",
      "active": true,
      "recurring": {
        "interval": "month",
        "interval_count": 1,
        "usage_type": "licensed"
      },
      "tax_behavior": "string",
      "type": "string",
      "unit_amount_decimal": "string"
    }
  ],
  "has_more": true
}

Response

200OKBackend_PricingListDto

Successful Response

Response fields application/json

pricingsArray<Backend_PricingDto>required

Show child attributes

idstringrequired

currencystringrequired

unit_amountintegerrequired

productstringrequired

activebooleanrequired

recurringBackend_RecurringDtorequired

Show child attributes

intervalstringdayweekmonthyearmonth

Billing interval, e.g., 'month'

interval_countinteger1

Number of intervals between each billing cycle

usage_typestringlicensedmeteredlicensed

Configures how the quantity per period should be determined. Can be either metered or licensed. licensed automatically bills the quantity set when adding it to a subscription. metered aggregates the total usage based on usage records. Defaults to licensed.

tax_behaviorstringrequired

typestringrequired

unit_amount_decimalstringrequired

has_morebooleanrequired

Authorization

OAuth2PasswordBeareroauth2

Create Pricing

POST

http://localhost:8000/api/v1/prices

Create Pricing

curl -X POST 'http://localhost:8000/api/v1/prices' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "currency": "usd",
  "unit_amount": 0,
  "product": "string",
  "active": true,
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "usage_type": "licensed"
  }
}'

const body = `{
  "currency": "usd",
  "unit_amount": 0,
  "product": "string",
  "active": true,
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "usage_type": "licensed"
  }
}`;

const response = await fetch('http://localhost:8000/api/v1/prices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "currency": "usd",
  "unit_amount": 0,
  "product": "string",
  "active": true,
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "usage_type": "licensed"
  }
}'''

response = requests.post(
    'http://localhost:8000/api/v1/prices',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "currency": "usd",
  "unit_amount": 0,
  "product": "string",
  "active": true,
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "usage_type": "licensed"
  }
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

currencystringusd

Currency code, e.g., 'usd'

unit_amountintegerrequired

A positive integer in cents (or 0 for a free price) representing how much to charge. One of unit_amount, unit_amount_decimal, or custom_unit_amount is required, unless billing_scheme=tiered.

productstringrequired

The ID of the product this price is associated with

activebooleantrue

Whether the price is active or not

recurringBackend_RecurringDtorequired

Show child attributes

intervalstringdayweekmonthyearmonth

Billing interval, e.g., 'month'

interval_countinteger1

Number of intervals between each billing cycle

usage_typestringlicensedmeteredlicensed

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update Pricing

PATCH

http://localhost:8000/api/v1/prices/{price_id}

Update Pricing

curl -X PATCH 'http://localhost:8000/api/v1/prices/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "active": true,
  "metadata": {},
  "tax_behavior": "exclusive"
}'

const body = `{
  "active": true,
  "metadata": {},
  "tax_behavior": "exclusive"
}`;

const response = await fetch('http://localhost:8000/api/v1/prices/string', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "active": true,
  "metadata": {},
  "tax_behavior": "exclusive"
}'''

response = requests.patch(
    'http://localhost:8000/api/v1/prices/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "active": true,
  "metadata": {},
  "tax_behavior": "exclusive"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

activebooleanrequired

metadataobject | null

Show child attributes

Any of

object

null

tax_behaviorstring | null

Show child attributes

Any of

stringexclusiveinclusiveunspecified

null

Parameters

price_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Stripe - Billing

Stripe - Billing — Backend

Get billing configuration

GET

http://localhost:8000/api/v1/billing/config

Returns the Stripe publishable key to the frontend.

Get billing configuration

curl -X GET 'http://localhost:8000/api/v1/billing/config' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/billing/config', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/billing/config',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "publishable_key": "string"
}

Response

200OKBackend_BillingConfigDto

Successful Response

Response fields application/json

publishable_keystringrequired

Authorization

OAuth2PasswordBeareroauth2

List available plans

GET

http://localhost:8000/api/v1/billing/plans

List available plans

curl -X GET 'http://localhost:8000/api/v1/billing/plans?skip=0&limit=10' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/billing/plans?skip=0&limit=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/billing/plans?skip=0&limit=10',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "active": true,
      "amount": 0,
      "amount_decimal": "string",
      "billing_scheme": "string",
      "currency": "usd",
      "interval": "string",
      "interval_count": 0,
      "product": "string",
      "trial_period_days": 0,
      "usage_type": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 10,
  "has_next": false,
  "has_previous": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

skipinteger0query

limitinteger10query

searchstring | nullquery

Response

200OKBackend_PlanListDto

Successful Response

Response fields application/json

itemsArray<Backend_PlanDto>required

Show child attributes

idstringrequired

activebooleanrequired

amountintegerrequired

amount_decimalstringrequired

billing_schemestringrequired

currencystringusd

intervalstringrequired

interval_countintegerrequired

productstringrequired

trial_period_daysinteger | null

Show child attributes

Any of

integer

null

usage_typestringrequired

totalintegerrequired

skipinteger0

limitinteger10

has_nextbooleanfalse

has_previousbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Create a new plan

POST

http://localhost:8000/api/v1/billing/plans

Create a new plan

curl -X POST 'http://localhost:8000/api/v1/billing/plans' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "currency": "usd",
  "interval": "month",
  "product_id": "string",
  "amount": 0,
  "trial_period_days": 0
}'

const body = `{
  "currency": "usd",
  "interval": "month",
  "product_id": "string",
  "amount": 0,
  "trial_period_days": 0
}`;

const response = await fetch('http://localhost:8000/api/v1/billing/plans', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "currency": "usd",
  "interval": "month",
  "product_id": "string",
  "amount": 0,
  "trial_period_days": 0
}'''

response = requests.post(
    'http://localhost:8000/api/v1/billing/plans',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "currency": "usd",
  "interval": "month",
  "product_id": "string",
  "amount": 0,
  "trial_period_days": 0
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

currencystringusd

Must be a supported currency: https://docs.stripe.com/currencies

intervalstringmonthyearrequired

product_idstringrequired

The product whose pricing the created plan will represent. This must be the ID of an existing product.

amountintegerrequired

trial_period_daysinteger | null

Number of days for the trial period. Set > 0 to enable trials.

Show child attributes

Any of

integer

null

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get a plan details

GET

http://localhost:8000/api/v1/billing/plans/{plan_id}

Get a plan details

curl -X GET 'http://localhost:8000/api/v1/billing/plans/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/billing/plans/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/billing/plans/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "active": true,
  "amount": 0,
  "amount_decimal": "string",
  "billing_scheme": "string",
  "currency": "usd",
  "interval": "string",
  "interval_count": 0,
  "product": "string",
  "trial_period_days": 0,
  "usage_type": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

plan_idstringrequiredpath

Response

200OKBackend_PlanDto

Successful Response

Response fields application/json

idstringrequired

activebooleanrequired

amountintegerrequired

amount_decimalstringrequired

billing_schemestringrequired

currencystringusd

intervalstringrequired

interval_countintegerrequired

productstringrequired

trial_period_daysinteger | null

Show child attributes

Any of

integer

null

usage_typestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Delete existing plan

DELETE

http://localhost:8000/api/v1/billing/plans/{plan_id}

Delete existing plan

curl -X DELETE 'http://localhost:8000/api/v1/billing/plans/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/billing/plans/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8000/api/v1/billing/plans/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

plan_idstringrequiredpath

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update a existing plan

PATCH

http://localhost:8000/api/v1/billing/plans/{plan_id}

Update a existing plan

curl -X PATCH 'http://localhost:8000/api/v1/billing/plans/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "trial_period_days": 0,
  "active": true,
  "metadata": {}
}'

const body = `{
  "trial_period_days": 0,
  "active": true,
  "metadata": {}
}`;

const response = await fetch('http://localhost:8000/api/v1/billing/plans/string', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "trial_period_days": 0,
  "active": true,
  "metadata": {}
}'''

response = requests.patch(
    'http://localhost:8000/api/v1/billing/plans/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "trial_period_days": 0,
  "active": true,
  "metadata": {}
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

trial_period_daysintegerrequired

activebooleantrue

metadataobject | null

Show child attributes

Any of

object

null

Parameters

plan_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Create a Stripe SetupIntent for adding a payment method inline

POST

http://localhost:8000/api/v1/billing/payment-methods/setup-intent

Returns a Stripe SetupIntent client_secret. The frontend uses this with Stripe.js confirmCardSetup() to save a card without charging it.

Create a Stripe SetupIntent for adding a payment method inline

curl -X POST 'http://localhost:8000/api/v1/billing/payment-methods/setup-intent' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/billing/payment-methods/setup-intent', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/billing/payment-methods/setup-intent',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

201

{
  "client_secret": "string",
  "setup_intent_id": "string"
}

Response

201CreatedBackend_SetupIntentDto

Successful Response

Response fields application/json

client_secretstringrequired

setup_intent_idstringrequired

Authorization

OAuth2PasswordBeareroauth2

List saved payment methods for the current tenant

GET

http://localhost:8000/api/v1/billing/payment-methods

List saved payment methods for the current tenant

curl -X GET 'http://localhost:8000/api/v1/billing/payment-methods' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/billing/payment-methods', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/billing/payment-methods',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "items": [
    {
      "id": "string",
      "type": "string",
      "card": {
        "brand": "string",
        "last4": "string",
        "exp_month": 0,
        "exp_year": 0,
        "country": "string"
      },
      "created": 0,
      "is_default": false
    }
  ],
  "customer_id": "string"
}

Response

200OKBackend_PaymentMethodListDto

Successful Response

Response fields application/json

itemsArray<Backend_PaymentMethodDto>required

Show child attributes

idstringrequired

typestringrequired

cardBackend_PaymentMethodCardDto | null

Show child attributes

Any of

brandstringrequired

last4stringrequired

exp_monthintegerrequired

exp_yearintegerrequired

countrystring | null

Show child attributes

Any of

string

null

createdintegerrequired

is_defaultbooleanfalse

customer_idstring | null

Show child attributes

Any of

string

null

Authorization

OAuth2PasswordBeareroauth2

Remove a saved payment method

DELETE

http://localhost:8000/api/v1/billing/payment-methods/{payment_method_id}

Remove a saved payment method

curl -X DELETE 'http://localhost:8000/api/v1/billing/payment-methods/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/billing/payment-methods/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8000/api/v1/billing/payment-methods/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

payment_method_idstringrequiredpath

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Set a payment method as the default for the tenant

POST

http://localhost:8000/api/v1/billing/payment-methods/{payment_method_id}/default

Set a payment method as the default for the tenant

curl -X POST 'http://localhost:8000/api/v1/billing/payment-methods/string/default' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/billing/payment-methods/string/default', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/billing/payment-methods/string/default',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

payment_method_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Sync tenant subscription with Stripe

POST

http://localhost:8000/api/v1/billing/sync

Sync tenant subscription with Stripe.

Sync tenant subscription with Stripe

curl -X POST 'http://localhost:8000/api/v1/billing/sync' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/billing/sync', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/billing/sync',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Authorization

OAuth2PasswordBeareroauth2

Create native subscription intent (compatibility endpoint)

POST

http://localhost:8000/api/v1/billing/subscription/create-intent

Create native subscription for tenant using Stripe Elements.

Create native subscription intent (compatibility endpoint)

curl -X POST 'http://localhost:8000/api/v1/billing/subscription/create-intent' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "string"
}'

const body = `{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/billing/subscription/create-intent', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/billing/subscription/create-intent',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "string"
}

{
  "client_secret": "string",
  "subscription_id": "string",
  "customer_id": "string",
  "billing_record_id": "string",
  "is_upgrade": false,
  "requires_confirmation": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

price_idstringrequired

tenant_idstringrequired

modestringsubscriptionpaymentsubscription

emailstringrequired

Response

201CreatedBackend_NativeSubscriptionResponseDto

Successful Response

Response fields application/json

client_secretstringrequired

subscription_idstringrequired

customer_idstringrequired

billing_record_idstringrequired

is_upgradebooleanfalse

requires_confirmationbooleantrue

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Create native subscription intent with Stripe Elements

POST

http://localhost:8000/api/v1/billing/native-subscription

Create native subscription for tenant using Stripe Elements.

Create native subscription intent with Stripe Elements

curl -X POST 'http://localhost:8000/api/v1/billing/native-subscription' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "string"
}'

const body = `{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/billing/native-subscription', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/billing/native-subscription',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "string"
}

{
  "client_secret": "string",
  "subscription_id": "string",
  "customer_id": "string",
  "billing_record_id": "string",
  "is_upgrade": false,
  "requires_confirmation": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

price_idstringrequired

tenant_idstringrequired

modestringsubscriptionpaymentsubscription

emailstringrequired

Response

201CreatedBackend_NativeSubscriptionResponseDto

Successful Response

Response fields application/json

client_secretstringrequired

subscription_idstringrequired

customer_idstringrequired

billing_record_idstringrequired

is_upgradebooleanfalse

requires_confirmationbooleantrue

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Confirm native subscription (compatibility endpoint)

POST

http://localhost:8000/api/v1/billing/subscription/confirm

Confirm native subscription: update billing record and sync tenant subscription with Stripe.

Confirm native subscription (compatibility endpoint)

curl -X POST 'http://localhost:8000/api/v1/billing/subscription/confirm' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "billing_record_id": "string"
}'

const body = `{
  "billing_record_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/billing/subscription/confirm', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "billing_record_id": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/billing/subscription/confirm',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "billing_record_id": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

billing_record_idstringrequired

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Confirm native subscription and sync tenant data

POST

http://localhost:8000/api/v1/billing/native-subscription/confirm

Confirm native subscription: update billing record and sync tenant subscription with Stripe.

Confirm native subscription and sync tenant data

curl -X POST 'http://localhost:8000/api/v1/billing/native-subscription/confirm' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "billing_record_id": "string"
}'

const body = `{
  "billing_record_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/billing/native-subscription/confirm', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "billing_record_id": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/billing/native-subscription/confirm',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "billing_record_id": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

billing_record_idstringrequired

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Create payment intent for incomplete subscription

POST

http://localhost:8000/api/v1/billing/subscription/complete-payment

Create a payment intent for an incomplete subscription so the user can complete payment.

Create payment intent for incomplete subscription

curl -X POST 'http://localhost:8000/api/v1/billing/subscription/complete-payment' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "subscription_id": "string",
  "tenant_id": "string"
}'

const body = `{
  "subscription_id": "string",
  "tenant_id": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/billing/subscription/complete-payment', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "subscription_id": "string",
  "tenant_id": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/billing/subscription/complete-payment',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "subscription_id": "string",
  "tenant_id": "string"
}

{
  "client_secret": "string",
  "subscription_id": "string",
  "customer_id": "string",
  "billing_record_id": "string",
  "is_upgrade": false,
  "requires_confirmation": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

subscription_idstringrequired

tenant_idstringrequired

Response

201CreatedBackend_NativeSubscriptionResponseDto

Successful Response

Response fields application/json

client_secretstringrequired

subscription_idstringrequired

customer_idstringrequired

billing_record_idstringrequired

is_upgradebooleanfalse

requires_confirmationbooleantrue

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get current tenant subscription status

GET

http://localhost:8000/api/v1/billing/subscription/status

Returns the current tenant's subscription status including dormant state.

Get current tenant subscription status

curl -X GET 'http://localhost:8000/api/v1/billing/subscription/status' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/billing/subscription/status', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/billing/subscription/status',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Authorization

OAuth2PasswordBeareroauth2

Downgrade dormant tenant to Free plan

POST

http://localhost:8000/api/v1/billing/subscription/downgrade-to-free

Downgrade a dormant/expired tenant to the Free plan. Cancels Stripe subscription but preserves all tenant data.

Downgrade dormant tenant to Free plan

curl -X POST 'http://localhost:8000/api/v1/billing/subscription/downgrade-to-free' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/billing/subscription/downgrade-to-free', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/billing/subscription/downgrade-to-free',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Authorization

OAuth2PasswordBeareroauth2

Backend / Webhooks - Stripe

Webhooks - Stripe — Backend

Stripe Webhook

POST

http://localhost:8000/api/v1/stripe/webhooks

Stripe Webhook

curl -X POST 'http://localhost:8000/api/v1/stripe/webhooks'

const response = await fetch('http://localhost:8000/api/v1/stripe/webhooks', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8000/api/v1/stripe/webhooks')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Backend / Stripe - Invoices

Stripe - Invoices — Backend

List invoices

GET

http://localhost:8000/api/v1/invoices

List invoices

curl -X GET 'http://localhost:8000/api/v1/invoices?skip=0&limit=10' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/invoices?skip=0&limit=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/invoices?skip=0&limit=10',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "amount_due": 0,
      "amount_paid": 0,
      "amount_remaining": 0,
      "amount_overpaid": 0,
      "attempt_count": 0,
      "attempted": false,
      "auto_advance": false,
      "billing_reason": "string",
      "collection_method": "string",
      "created": 0,
      "currency": "usd",
      "customer": "string",
      "customer_name": "string",
      "status": "open",
      "total": 0,
      "receipt_number": "string",
      "amount_country": "string",
      "account_name": "string",
      "invoice_pdf": "string",
      "hosted_invoice_url": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 10,
  "has_next": false,
  "has_previous": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

skipinteger0query

limitinteger10query

searchstring | nullquery

Response

200OKBackend_InvoiceListDto

Successful Response

Response fields application/json

itemsArray<Backend_InvoiceDto>required

Show child attributes

idstringrequired

amount_dueinteger0

amount_paidinteger0

amount_remaininginteger0

amount_overpaidinteger0

attempt_countinteger0

attemptedbooleanfalse

auto_advancebooleanfalse

billing_reasonstring | null

Show child attributes

Any of

string

null

collection_methodstring | null

Show child attributes

Any of

string

null

createdintegerrequired

currencystringusd

customerstring | null

Show child attributes

Any of

string

null

customer_namestring | null

Show child attributes

Any of

string

null

statusstringopen

totalinteger0

receipt_numberstring | null

Show child attributes

Any of

string

null

amount_countrystring | null

Show child attributes

Any of

string

null

account_namestring | null

Show child attributes

Any of

string

null

invoice_pdfstring | null

Show child attributes

Any of

string

null

hosted_invoice_urlstring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipinteger0

limitinteger10

has_nextbooleanfalse

has_previousbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

List subscription history

GET

http://localhost:8000/api/v1/invoices/history

List subscription history

curl -X GET 'http://localhost:8000/api/v1/invoices/history?skip=0&limit=10' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/invoices/history?skip=0&limit=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/invoices/history?skip=0&limit=10',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "created_at": "string",
      "scope": "host",
      "actor": "tenant",
      "user_id": "string",
      "user_name": "string",
      "user_email": "string",
      "payment_type": "string",
      "currency": "string",
      "amount": 0,
      "amount_formatted": "string",
      "stripe_customer_id": "string",
      "stripe_subscription_id": "string",
      "stripe_session_id": "string",
      "stripe_invoice_id": "string",
      "stripe_payment_intent_id": "string",
      "product_id": "string",
      "price_id": "string",
      "status": "pending",
      "current_period_end": "string",
      "canceled_at": "string",
      "cancellation_reason": "string",
      "invoice_url": "string",
      "invoice_pdf_url": "string",
      "receipt_url": "string",
      "metadata": {}
    }
  ],
  "skip": 0,
  "limit": 0,
  "total": 0,
  "has_previous": true,
  "has_next": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

skipinteger0query

limitinteger10query

searchstring | nullquery

Response

200OKBackend_BillingRecordListDto

Successful Response

Response fields application/json

itemsArray<Backend_BillingRecordDto>required

Show child attributes

idstringrequired

created_atstringrequired

scopestringhosttenantrequired

actorstringtenantend_userrequired

user_idstring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

user_emailstring | null

Show child attributes

Any of

string

null

payment_typestringrequired

currencystringrequired

amountinteger | null

Show child attributes

Any of

integer

null

amount_formattedstring | null

Show child attributes

Any of

string

null

stripe_customer_idstring | null

Show child attributes

Any of

string

null

stripe_subscription_idstring | null

Show child attributes

Any of

string

null

stripe_session_idstring | null

Show child attributes

Any of

string

null

stripe_invoice_idstring | null

Show child attributes

Any of

string

null

stripe_payment_intent_idstring | null

Show child attributes

Any of

string

null

product_idstring | null

Show child attributes

Any of

string

null

price_idstring | null

Show child attributes

Any of

string

null

statusstringpendingrequires_payment_methodrequires_actionactivesucceededpayment_failedcanceledincompleterequired

current_period_endstring | null

Show child attributes

Any of

string

null

canceled_atstring | null

Show child attributes

Any of

string

null

cancellation_reasonstring | null

Show child attributes

Any of

string

null

invoice_urlstring | null

Show child attributes

Any of

string

null

invoice_pdf_urlstring | null

Show child attributes

Any of

string

null

receipt_urlstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

skipintegerrequired

limitintegerrequired

totalintegerrequired

has_previousbooleanrequired

has_nextbooleanrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

List tenant invoices

GET

http://localhost:8000/api/v1/invoices/tenant

List invoices for the current tenant only, filtered by date range and status.

List tenant invoices

curl -X GET 'http://localhost:8000/api/v1/invoices/tenant?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/invoices/tenant?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/invoices/tenant?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "invoice_number": "string",
      "created": 0,
      "due_date": 0,
      "status": "open",
      "currency": "usd",
      "amount_due": 0,
      "amount_paid": 0,
      "tax_amount": 0,
      "total": 0,
      "billing_reason": "string",
      "customer_name": "string",
      "tenant_name": "string",
      "tenant_tax_id": "string",
      "invoice_pdf": "string",
      "hosted_invoice_url": "string",
      "line_items": []
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 10,
  "has_next": false,
  "has_previous": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

start_datestringquery

end_datestringquery

statusstringquery

skipinteger0query

limitinteger20query

searchstring | nullquery

Response

200OKBackend_TenantInvoiceListDto

Successful Response

Response fields application/json

itemsArray<Backend_TenantInvoiceExportDto>required

Show child attributes

idstringrequired

invoice_numberstring | null

Show child attributes

Any of

string

null

createdintegerrequired

due_dateinteger | null

Show child attributes

Any of

integer

null

statusstringopen

currencystringusd

amount_dueinteger0

amount_paidinteger0

tax_amountinteger0

totalinteger0

billing_reasonstring | null

Show child attributes

Any of

string

null

customer_namestring | null

Show child attributes

Any of

string

null

tenant_namestring | null

Show child attributes

Any of

string

null

tenant_tax_idstring | null

Show child attributes

Any of

string

null

invoice_pdfstring | null

Show child attributes

Any of

string

null

hosted_invoice_urlstring | null

Show child attributes

Any of

string

null

line_itemsArray<Backend_TenantInvoiceLineItemDto>

Show child attributes

descriptionstring | null

Show child attributes

Any of

string

null

quantityinteger1

unit_amountinteger0

amountinteger0

currencystringusd

totalintegerrequired

skipinteger0

limitinteger10

has_nextbooleanfalse

has_previousbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Export tenant invoices as CSV

GET

http://localhost:8000/api/v1/invoices/tenant/export

Export all tenant invoices as CSV for tax filing purposes.

Export tenant invoices as CSV

curl -X GET 'http://localhost:8000/api/v1/invoices/tenant/export' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/invoices/tenant/export', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/invoices/tenant/export',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

start_datestringquery

end_datestringquery

statusstringquery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Stripe - Checkout

Stripe - Checkout — Backend

Create Host Checkout Session

POST

http://localhost:8000/api/v1/checkouts/host/{tenant_id}/tenant

Create Host Checkout Session

curl -X POST 'http://localhost:8000/api/v1/checkouts/host/%7Btenant_id%7D/tenant' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "user@example.com"
}'

const body = `{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "user@example.com"
}`;

const response = await fetch('http://localhost:8000/api/v1/checkouts/host/%7Btenant_id%7D/tenant', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "user@example.com"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/checkouts/host/%7Btenant_id%7D/tenant',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "user@example.com"
}

{
  "checkout_url": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

price_idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

modestringpaymentsubscriptionsetupsubscription

emailstring<email>required

Response

200OKBackend_CheckoutResponseDto

Successful Response

Response fields application/json

checkout_urlstringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Create Tenant Subscription Checkout

POST

http://localhost:8000/api/v1/checkouts/tenant/subscription

Create a Stripe checkout session for tenant subscription. Uses host-level Stripe settings (NOT tenant-specific). Host charges tenants for their subscriptions.

Create Tenant Subscription Checkout

curl -X POST 'http://localhost:8000/api/v1/checkouts/tenant/subscription' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "user@example.com"
}'

const body = `{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "user@example.com"
}`;

const response = await fetch('http://localhost:8000/api/v1/checkouts/tenant/subscription', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "user@example.com"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/checkouts/tenant/subscription',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "price_id": "string",
  "tenant_id": "string",
  "mode": "subscription",
  "email": "user@example.com"
}

{
  "checkout_url": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

price_idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

modestringpaymentsubscriptionsetupsubscription

emailstring<email>required

Response

200OKBackend_CheckoutResponseDto

Successful Response

Response fields application/json

checkout_urlstringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Host Checkout Success

POST

http://localhost:8000/api/v1/checkouts/host/payment/success

Host Checkout Success

curl -X POST 'http://localhost:8000/api/v1/checkouts/host/payment/success?session_id=string&tenant_id=string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/checkouts/host/payment/success?session_id=string&tenant_id=string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/checkouts/host/payment/success?session_id=string&tenant_id=string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

session_idstringrequiredquery

tenant_idstringrequiredquery

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Host Checkout Canceled

POST

http://localhost:8000/api/v1/checkouts/host/payment/cancel

Host Checkout Canceled

curl -X POST 'http://localhost:8000/api/v1/checkouts/host/payment/cancel?tenant_id=string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/checkouts/host/payment/cancel?tenant_id=string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/checkouts/host/payment/cancel?tenant_id=string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

tenant_idstringrequiredquery

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Tenant Checkout Success

POST

http://localhost:8000/api/v1/checkouts/tenant/payment/success

Handle successful tenant subscription checkout. Uses host-level Stripe settings.

Tenant Checkout Success

curl -X POST 'http://localhost:8000/api/v1/checkouts/tenant/payment/success?session_id=string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/checkouts/tenant/payment/success?session_id=string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/checkouts/tenant/payment/success?session_id=string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

session_idstringrequiredquery

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Tenant Checkout Canceled

POST

http://localhost:8000/api/v1/checkouts/tenant/payment/cancel

Handle cancelled tenant subscription checkout.

Tenant Checkout Canceled

curl -X POST 'http://localhost:8000/api/v1/checkouts/tenant/payment/cancel' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/checkouts/tenant/payment/cancel', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8000/api/v1/checkouts/tenant/payment/cancel',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

202Acceptedany

Successful Response

Response fields application/json

any

Authorization

OAuth2PasswordBeareroauth2

List Checkout Records

GET

http://localhost:8000/api/v1/checkouts/all

List Checkout Records

curl -X GET 'http://localhost:8000/api/v1/checkouts/all?skip=0&limit=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/checkouts/all?skip=0&limit=100', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/checkouts/all?skip=0&limit=100',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "created_at": "string",
      "scope": "host",
      "actor": "tenant",
      "user_id": "string",
      "user_name": "string",
      "user_email": "string",
      "payment_type": "string",
      "currency": "string",
      "amount": 0,
      "amount_formatted": "string",
      "stripe_customer_id": "string",
      "stripe_subscription_id": "string",
      "stripe_session_id": "string",
      "stripe_invoice_id": "string",
      "stripe_payment_intent_id": "string",
      "product_id": "string",
      "price_id": "string",
      "status": "pending",
      "current_period_end": "string",
      "canceled_at": "string",
      "cancellation_reason": "string",
      "invoice_url": "string",
      "invoice_pdf_url": "string",
      "receipt_url": "string",
      "metadata": {}
    }
  ],
  "skip": 0,
  "limit": 0,
  "total": 0,
  "has_previous": true,
  "has_next": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

skipinteger0query

limitinteger100query

searchstring | nullquery

Response

200OKBackend_BillingRecordListDto

Successful Response

Response fields application/json

itemsArray<Backend_BillingRecordDto>required

Show child attributes

idstringrequired

created_atstringrequired

scopestringhosttenantrequired

actorstringtenantend_userrequired

user_idstring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

user_emailstring | null

Show child attributes

Any of

string

null

payment_typestringrequired

currencystringrequired

amountinteger | null

Show child attributes

Any of

integer

null

amount_formattedstring | null

Show child attributes

Any of

string

null

stripe_customer_idstring | null

Show child attributes

Any of

string

null

stripe_subscription_idstring | null

Show child attributes

Any of

string

null

stripe_session_idstring | null

Show child attributes

Any of

string

null

stripe_invoice_idstring | null

Show child attributes

Any of

string

null

stripe_payment_intent_idstring | null

Show child attributes

Any of

string

null

product_idstring | null

Show child attributes

Any of

string

null

price_idstring | null

Show child attributes

Any of

string

null

statusstringpendingrequires_payment_methodrequires_actionactivesucceededpayment_failedcanceledincompleterequired

current_period_endstring | null

Show child attributes

Any of

string

null

canceled_atstring | null

Show child attributes

Any of

string

null

cancellation_reasonstring | null

Show child attributes

Any of

string

null

invoice_urlstring | null

Show child attributes

Any of

string

null

invoice_pdf_urlstring | null

Show child attributes

Any of

string

null

receipt_urlstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

skipintegerrequired

limitintegerrequired

totalintegerrequired

has_previousbooleanrequired

has_nextbooleanrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Notifications

Notifications — Backend

Get Notification Banner

GET

http://localhost:8000/api/v1/notifications/banner

Get the current notification banner information.

Get Notification Banner

curl -X GET 'http://localhost:8000/api/v1/notifications/banner'

const response = await fetch('http://localhost:8000/api/v1/notifications/banner', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8000/api/v1/notifications/banner')
print(response.text)

200

{
  "is_enabled": true,
  "message": "string",
  "id": "string",
  "tenant_id": "string",
  "created_at": "string",
  "updated_at": "string"
}

Response

200OKBackend_NotificationBannerSettingDto

Successful Response

Response fields application/json

is_enabledbooleanrequired

messagestring | null

Show child attributes

Any of

string

null

idstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

Create Notification Banner

POST

http://localhost:8000/api/v1/notifications/banner

Create a new notification banner setting.

Create Notification Banner

curl -X POST 'http://localhost:8000/api/v1/notifications/banner' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "is_enabled": true,
  "message": "string"
}'

const body = `{
  "is_enabled": true,
  "message": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/notifications/banner', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "is_enabled": true,
  "message": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/notifications/banner',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "is_enabled": true,
  "message": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

is_enabledbooleanrequired

messagestring | null

Show child attributes

Any of

string

null

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update Notification Banner

PUT

http://localhost:8000/api/v1/notifications/banner/{id}

Update an existing notification banner setting.

Update Notification Banner

curl -X PUT 'http://localhost:8000/api/v1/notifications/banner/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "is_enabled": true,
  "message": "string"
}'

const body = `{
  "is_enabled": true,
  "message": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/notifications/banner/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "is_enabled": true,
  "message": "string"
}'''

response = requests.put(
    'http://localhost:8000/api/v1/notifications/banner/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "is_enabled": true,
  "message": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

is_enabledbooleanrequired

messagestring | null

Show child attributes

Any of

string

null

Backend / Audit Logs

Audit Logs — Backend

Download Audit Logs

POST

http://localhost:8000/api/v1/audit-logs/download

Download Audit Logs

curl -X POST 'http://localhost:8000/api/v1/audit-logs/download' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "action": "create",
  "total_records": 0
}'

const body = `{
  "action": "create",
  "total_records": 0
}`;

const response = await fetch('http://localhost:8000/api/v1/audit-logs/download', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "action": "create",
  "total_records": 0
}'''

response = requests.post(
    'http://localhost:8000/api/v1/audit-logs/download',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "action": "create",
  "total_records": 0
}

{
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

actionstring | null

Show child attributes

Any of

stringcreateupdatedeletereadloginlogouterrordownload

null

total_recordsintegerrequired

Response

202AcceptedBackend_DownloadResponseDto

Successful Response

Response fields application/json

messagestringrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Get User Activity Logs

GET

http://localhost:8000/api/v1/users/{user_id}/activity-logs

Get User Activity Logs

curl -X GET 'http://localhost:8000/api/v1/users/string/activity-logs?limit=10&skip=0' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/users/string/activity-logs?limit=10&skip=0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/users/string/activity-logs?limit=10&skip=0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "total": 0,
  "items": [
    {
      "id": "string",
      "entity": "string",
      "service_name": "string",
      "action": "create",
      "changes": {},
      "user_id": "string",
      "timestamp": "",
      "tenant_id": "string",
      "actor_name": "string",
      "actor_email": "string",
      "resource_id": "string",
      "resource_name": "string",
      "category": "string",
      "severity": "string",
      "description": "string",
      "failure_reason": "string",
      "correlation_id": "string",
      "status": "string",
      "ip_address": "string",
      "user_agent": "string",
      "event_type": "string"
    }
  ],
  "has_next": true,
  "has_previous": true,
  "limit": 0,
  "skip": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

user_idstringrequiredpath

limitinteger10query

skipinteger0query

actionstring | nullquery

categorystring | nullquery

searchstring | nullquery

date_fromstring | nullquery

date_tostring | nullquery

Response

200OKBackend_AuditLogListDto

Successful Response

Response fields application/json

totalintegerrequired

itemsArray<Backend_AuditLogDto>required

Show child attributes

idstring | null

Show child attributes

Any of

string

null

entitystringrequired

service_namestring | null

Show child attributes

Any of

string

null

actionstringcreateupdatedeletereadloginlogouterrordownloadrequired

changesobject

user_idstring | null

Show child attributes

Any of

string

null

timestampstring

tenant_idstring | null

Show child attributes

Any of

string

null

actor_namestring | null

Show child attributes

Any of

string

null

actor_emailstring | null

Show child attributes

Any of

string

null

resource_idstring | null

Show child attributes

Any of

string

null

resource_namestring | null

Show child attributes

Any of

string

null

categorystring | null

Show child attributes

Any of

string

null

severitystring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

failure_reasonstring | null

Show child attributes

Any of

string

null

correlation_idstring | null

Show child attributes

Any of

string

null

statusstring | null

Show child attributes

Any of

string

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

event_typestring | null

Show child attributes

Any of

string

null

has_nextbooleanrequired

has_previousbooleanrequired

limitintegerrequired

skipintegerrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Frontend Logs

Frontend Logs — Backend

Create Frontend Log

POST

http://localhost:8000/api/v1/frontend-logs

Receive frontend log entry and write to frontend/logs directory.

This endpoint accepts logs from the frontend and stores them in:

frontend/logs/frontend-all.log (all logs)
frontend/logs/frontend-errors.log (ERROR and FATAL only)

Logs are stored in JSON Lines format (one JSON object per line).

Create Frontend Log

curl -X POST 'http://localhost:8000/api/v1/frontend-logs' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "timestamp": "string",
  "level": "string",
  "message": "string",
  "context": {},
  "stack": "string",
  "userAgent": "string",
  "url": "string",
  "userId": "string",
  "tenantId": "string"
}'

const body = `{
  "timestamp": "string",
  "level": "string",
  "message": "string",
  "context": {},
  "stack": "string",
  "userAgent": "string",
  "url": "string",
  "userId": "string",
  "tenantId": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/frontend-logs', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "timestamp": "string",
  "level": "string",
  "message": "string",
  "context": {},
  "stack": "string",
  "userAgent": "string",
  "url": "string",
  "userId": "string",
  "tenantId": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/frontend-logs',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "timestamp": "string",
  "level": "string",
  "message": "string",
  "context": {},
  "stack": "string",
  "userAgent": "string",
  "url": "string",
  "userId": "string",
  "tenantId": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

Frontend log entry model

timestampstringrequired

levelstringrequired

messagestringrequired

contextobject | null

Show child attributes

Any of

object

null

stackstring | null

Show child attributes

Any of

string

null

userAgentstring | null

Show child attributes

Any of

string

null

urlstring | null

Show child attributes

Any of

string

null

userIdstring | null

Show child attributes

Any of

string

null

tenantIdstring | null

Show child attributes

Any of

string

null

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Health Check

GET

http://localhost:8000/api/v1/frontend-logs/health

Health check for frontend logging endpoint

Health Check

curl -X GET 'http://localhost:8000/api/v1/frontend-logs/health'

const response = await fetch('http://localhost:8000/api/v1/frontend-logs/health', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8000/api/v1/frontend-logs/health')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Backend / Frontend Audit

Frontend Audit — Backend

Ingest Audit Event

POST

http://localhost:8000/api/v1/frontend-audit/logs

Relay a client-originated audit event to the centralized audit-service.

The browser cannot call the audit-service's internal-only ingest endpoint (service_only=True). This endpoint accepts authenticated user events and forwards them with the backend's service token, pinning the actor to the authenticated user so clients cannot forge audit entries.

Ingest Audit Event

curl -X POST 'http://localhost:8000/api/v1/frontend-audit/logs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "event_id": "string",
  "event_type": "string",
  "log_schema_version": "1.0",
  "service_name": "frontend",
  "action": "string",
  "actor_type": "string",
  "actor_id": "string",
  "actor_email": "string",
  "tenant_id": "string",
  "resource_type": "string",
  "resource_id": "string",
  "status": "success",
  "ip_address": "string",
  "user_agent": "string",
  "request_id": "string",
  "trace_id": "string",
  "parent_trace_id": "string",
  "http_method": "string",
  "http_path": "string",
  "http_status": 0,
  "duration_ms": 0,
  "metadata": {},
  "event_idempotency_key": "string",
  "data_classification": "string"
}'

const body = `{
  "event_id": "string",
  "event_type": "string",
  "log_schema_version": "1.0",
  "service_name": "frontend",
  "action": "string",
  "actor_type": "string",
  "actor_id": "string",
  "actor_email": "string",
  "tenant_id": "string",
  "resource_type": "string",
  "resource_id": "string",
  "status": "success",
  "ip_address": "string",
  "user_agent": "string",
  "request_id": "string",
  "trace_id": "string",
  "parent_trace_id": "string",
  "http_method": "string",
  "http_path": "string",
  "http_status": 0,
  "duration_ms": 0,
  "metadata": {},
  "event_idempotency_key": "string",
  "data_classification": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/frontend-audit/logs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "event_id": "string",
  "event_type": "string",
  "log_schema_version": "1.0",
  "service_name": "frontend",
  "action": "string",
  "actor_type": "string",
  "actor_id": "string",
  "actor_email": "string",
  "tenant_id": "string",
  "resource_type": "string",
  "resource_id": "string",
  "status": "success",
  "ip_address": "string",
  "user_agent": "string",
  "request_id": "string",
  "trace_id": "string",
  "parent_trace_id": "string",
  "http_method": "string",
  "http_path": "string",
  "http_status": 0,
  "duration_ms": 0,
  "metadata": {},
  "event_idempotency_key": "string",
  "data_classification": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/frontend-audit/logs',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "event_id": "string",
  "event_type": "string",
  "log_schema_version": "1.0",
  "service_name": "frontend",
  "action": "string",
  "actor_type": "string",
  "actor_id": "string",
  "actor_email": "string",
  "tenant_id": "string",
  "resource_type": "string",
  "resource_id": "string",
  "status": "success",
  "ip_address": "string",
  "user_agent": "string",
  "request_id": "string",
  "trace_id": "string",
  "parent_trace_id": "string",
  "http_method": "string",
  "http_path": "string",
  "http_status": 0,
  "duration_ms": 0,
  "metadata": {},
  "event_idempotency_key": "string",
  "data_classification": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

Client-originated audit event relayed to the centralized audit-service.

Mirrors the schema the browser sends via the generated AuditLogsService (createAuditLog). Unknown fields are preserved (extra="allow") so the relay forwards the payload faithfully to the audit-service, which owns validation.

event_idstring | null

Show child attributes

Any of

string

null

event_typestring | null

Show child attributes

Any of

string

null

log_schema_versionstring | null1.0

Show child attributes

Any of

string

null

service_namestringfrontend

actionstringrequired

actor_typestring | null

Show child attributes

Any of

string

null

actor_idstring | null

Show child attributes

Any of

string

null

actor_emailstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

resource_typestring | null

Show child attributes

Any of

string

null

resource_idstring | null

Show child attributes

Any of

string

null

statusstring | nullsuccess

Show child attributes

Any of

string

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

request_idstring | null

Show child attributes

Any of

string

null

trace_idstring | null

Show child attributes

Any of

string

null

parent_trace_idstring | null

Show child attributes

Any of

string

null

http_methodstring | null

Show child attributes

Any of

string

null

http_pathstring | null

Show child attributes

Any of

string

null

http_statusinteger | null

Show child attributes

Any of

integer

null

duration_msinteger | null

Show child attributes

Any of

integer

null

metadataobject | null

Show child attributes

Any of

object

null

event_idempotency_keystring | null

Show child attributes

Any of

string

null

data_classificationstring | null

Show child attributes

Any of

string

null

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Mobile Security Policies (DEPRECATED)

Mobile Security Policies (DEPRECATED) — Backend

Get Deprecated Mobile Security Policy

deprecated

GET

http://localhost:8000/api/v1/mobile-security-policies/{tenant_id}

DEPRECATED: Use GET /tenant-governance/{tenant_id} + GET /runtime-security-config/ instead.

Get Deprecated Mobile Security Policy

curl -X GET 'http://localhost:8000/api/v1/mobile-security-policies/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/mobile-security-policies/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/mobile-security-policies/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "tenant_id": "string",
  "global_mode": "warning",
  "screenshot_prevention_mode": "disabled",
  "root_detection_mode": "warning",
  "biometric_required_mode": "disabled",
  "session_timeout_minutes": 0,
  "wifi_only_sync": false,
  "battery_aware_sync": false,
  "battery_low_threshold_percent": 20,
  "block_sync_on_roaming": false,
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_DeprecatedMobileSecurityPolicyDto

Successful Response

Response fields application/json

Backward-compatible adapter for old mobile clients.

Maps from RuntimeSecurityConfig + TenantDataGovernance into the old monolithic MobileSecurityPolicyDto format. This is TEMPORARY — remove after migration window.

DEPRECATED: Use RuntimeSecurityConfigDto + TenantDataGovernanceDto instead.

idstring | null

Show child attributes

Any of

string

null

tenant_idstringrequired

global_modestringwarning

screenshot_prevention_modestringdisabled

root_detection_modestringwarning

biometric_required_modestringdisabled

session_timeout_minutesinteger0

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update Deprecated Mobile Security Policy

deprecated

PUT

http://localhost:8000/api/v1/mobile-security-policies/{tenant_id}

DEPRECATED: Use PUT /runtime-security-config/ + PUT /tenant-governance/{tenant_id} instead.

Extracts runtime-global fields and updates runtime_security_config. Extracts tenant-scoped fields and updates tenant_data_governance.

Update Deprecated Mobile Security Policy

curl -X PUT 'http://localhost:8000/api/v1/mobile-security-policies/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "id": "string",
  "tenant_id": "string",
  "global_mode": "warning",
  "screenshot_prevention_mode": "disabled",
  "root_detection_mode": "warning",
  "biometric_required_mode": "disabled",
  "session_timeout_minutes": 0,
  "wifi_only_sync": false,
  "battery_aware_sync": false,
  "battery_low_threshold_percent": 20,
  "block_sync_on_roaming": false,
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false
}'

const body = `{
  "id": "string",
  "tenant_id": "string",
  "global_mode": "warning",
  "screenshot_prevention_mode": "disabled",
  "root_detection_mode": "warning",
  "biometric_required_mode": "disabled",
  "session_timeout_minutes": 0,
  "wifi_only_sync": false,
  "battery_aware_sync": false,
  "battery_low_threshold_percent": 20,
  "block_sync_on_roaming": false,
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false
}`;

const response = await fetch('http://localhost:8000/api/v1/mobile-security-policies/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "id": "string",
  "tenant_id": "string",
  "global_mode": "warning",
  "screenshot_prevention_mode": "disabled",
  "root_detection_mode": "warning",
  "biometric_required_mode": "disabled",
  "session_timeout_minutes": 0,
  "wifi_only_sync": false,
  "battery_aware_sync": false,
  "battery_low_threshold_percent": 20,
  "block_sync_on_roaming": false,
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false
}'''

response = requests.put(
    'http://localhost:8000/api/v1/mobile-security-policies/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "id": "string",
  "tenant_id": "string",
  "global_mode": "warning",
  "screenshot_prevention_mode": "disabled",
  "root_detection_mode": "warning",
  "biometric_required_mode": "disabled",
  "session_timeout_minutes": 0,
  "wifi_only_sync": false,
  "battery_aware_sync": false,
  "battery_low_threshold_percent": 20,
  "block_sync_on_roaming": false,
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

Backward-compatible adapter for old mobile clients.

Maps from RuntimeSecurityConfig + TenantDataGovernance into the old monolithic MobileSecurityPolicyDto format. This is TEMPORARY — remove after migration window.

DEPRECATED: Use RuntimeSecurityConfigDto + TenantDataGovernanceDto instead.

idstring | null

Show child attributes

Any of

string

null

tenant_idstringrequired

global_modestringwarning

screenshot_prevention_modestringdisabled

root_detection_modestringwarning

biometric_required_modestringdisabled

session_timeout_minutesinteger0

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

Parameters

tenant_idstringrequiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Runtime Security Config

Runtime Security Config — Backend

Get Runtime Security Config

GET

http://localhost:8000/api/v1/runtime-security-config

Get Runtime Security Config

curl -X GET 'http://localhost:8000/api/v1/runtime-security-config' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/runtime-security-config', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/runtime-security-config',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "id": "system_default",
  "screenshot_prevention_mode": "disabled",
  "root_detection_mode": "warning",
  "biometric_required_mode": "disabled",
  "session_timeout_minutes": 0,
  "wifi_only_sync": false,
  "battery_aware_sync": false,
  "battery_low_threshold_percent": 20,
  "block_sync_on_roaming": false,
  "background_sync_enabled": true,
  "crash_reporting_enabled": true,
  "telemetry_enabled": true,
  "global_mode": "warning",
  "version_id": "string",
  "updated_at": "string",
  "updated_by": "string"
}

Response

200OKBackend_RuntimeSecurityConfigDto

Successful Response

Response fields application/json

idstringsystem_default

screenshot_prevention_modestringstrictwarningdisableddisabled

root_detection_modestringstrictwarningdisabledwarning

biometric_required_modestringstrictwarningdisableddisabled

session_timeout_minutesinteger0

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

background_sync_enabledbooleantrue

crash_reporting_enabledbooleantrue

telemetry_enabledbooleantrue

global_modestringstrictwarningdisabledwarning

version_idstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

updated_bystring | null

Show child attributes

Any of

string

null

Authorization

OAuth2PasswordBeareroauth2

Update Runtime Security Config

PUT

http://localhost:8000/api/v1/runtime-security-config

Update Runtime Security Config

curl -X PUT 'http://localhost:8000/api/v1/runtime-security-config' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "screenshot_prevention_mode": "strict",
  "root_detection_mode": "strict",
  "biometric_required_mode": "strict",
  "session_timeout_minutes": 0,
  "wifi_only_sync": true,
  "battery_aware_sync": true,
  "battery_low_threshold_percent": 1,
  "block_sync_on_roaming": true,
  "background_sync_enabled": true,
  "crash_reporting_enabled": true,
  "telemetry_enabled": true,
  "global_mode": "strict"
}'

const body = `{
  "screenshot_prevention_mode": "strict",
  "root_detection_mode": "strict",
  "biometric_required_mode": "strict",
  "session_timeout_minutes": 0,
  "wifi_only_sync": true,
  "battery_aware_sync": true,
  "battery_low_threshold_percent": 1,
  "block_sync_on_roaming": true,
  "background_sync_enabled": true,
  "crash_reporting_enabled": true,
  "telemetry_enabled": true,
  "global_mode": "strict"
}`;

const response = await fetch('http://localhost:8000/api/v1/runtime-security-config', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "screenshot_prevention_mode": "strict",
  "root_detection_mode": "strict",
  "biometric_required_mode": "strict",
  "session_timeout_minutes": 0,
  "wifi_only_sync": true,
  "battery_aware_sync": true,
  "battery_low_threshold_percent": 1,
  "block_sync_on_roaming": true,
  "background_sync_enabled": true,
  "crash_reporting_enabled": true,
  "telemetry_enabled": true,
  "global_mode": "strict"
}'''

response = requests.put(
    'http://localhost:8000/api/v1/runtime-security-config',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "screenshot_prevention_mode": "strict",
  "root_detection_mode": "strict",
  "biometric_required_mode": "strict",
  "session_timeout_minutes": 0,
  "wifi_only_sync": true,
  "battery_aware_sync": true,
  "battery_low_threshold_percent": 1,
  "block_sync_on_roaming": true,
  "background_sync_enabled": true,
  "crash_reporting_enabled": true,
  "telemetry_enabled": true,
  "global_mode": "strict"
}

{
  "id": "system_default",
  "screenshot_prevention_mode": "disabled",
  "root_detection_mode": "warning",
  "biometric_required_mode": "disabled",
  "session_timeout_minutes": 0,
  "wifi_only_sync": false,
  "battery_aware_sync": false,
  "battery_low_threshold_percent": 20,
  "block_sync_on_roaming": false,
  "background_sync_enabled": true,
  "crash_reporting_enabled": true,
  "telemetry_enabled": true,
  "global_mode": "warning",
  "version_id": "string",
  "updated_at": "string",
  "updated_by": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

screenshot_prevention_modestring | null

Show child attributes

Any of

stringstrictwarningdisabled

null

root_detection_modestring | null

Show child attributes

Any of

stringstrictwarningdisabled

null

biometric_required_modestring | null

Show child attributes

Any of

stringstrictwarningdisabled

null

session_timeout_minutesinteger | null

Show child attributes

Any of

integer[0, 1440]

null

wifi_only_syncboolean | null

Show child attributes

Any of

boolean

null

battery_aware_syncboolean | null

Show child attributes

Any of

boolean

null

battery_low_threshold_percentinteger | null

Show child attributes

Any of

integer[1, 100]

null

block_sync_on_roamingboolean | null

Show child attributes

Any of

boolean

null

background_sync_enabledboolean | null

Show child attributes

Any of

boolean

null

crash_reporting_enabledboolean | null

Show child attributes

Any of

boolean

null

telemetry_enabledboolean | null

Show child attributes

Any of

boolean

null

global_modestring | null

Show child attributes

Any of

stringstrictwarningdisabled

null

Response

200OKBackend_RuntimeSecurityConfigDto

Successful Response

Response fields application/json

idstringsystem_default

screenshot_prevention_modestringstrictwarningdisableddisabled

root_detection_modestringstrictwarningdisabledwarning

biometric_required_modestringstrictwarningdisableddisabled

session_timeout_minutesinteger0

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

background_sync_enabledbooleantrue

crash_reporting_enabledbooleantrue

telemetry_enabledbooleantrue

global_modestringstrictwarningdisabledwarning

version_idstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

updated_bystring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / Tenant Data Governance

Tenant Data Governance — Backend

Get Tenant Governance

GET

http://localhost:8000/api/v1/tenant-governance/{tenant_id}

Get Tenant Governance

curl -X GET 'http://localhost:8000/api/v1/tenant-governance/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/tenant-governance/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/tenant-governance/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "tenant_id": "string",
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false,
  "version_id": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_TenantDataGovernanceDto

Successful Response

Response fields application/json

idstring | null

Show child attributes

Any of

string

null

tenant_idstringrequired

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

version_idstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Update Tenant Governance

PUT

http://localhost:8000/api/v1/tenant-governance/{tenant_id}

Update Tenant Governance

curl -X PUT 'http://localhost:8000/api/v1/tenant-governance/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 1,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": true
}'

const body = `{
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 1,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": true
}`;

const response = await fetch('http://localhost:8000/api/v1/tenant-governance/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 1,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": true
}'''

response = requests.put(
    'http://localhost:8000/api/v1/tenant-governance/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 1,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": true
}

{
  "message": "string",
  "governance": {
    "id": "string",
    "tenant_id": "string",
    "max_offline_duration_hours": 0,
    "force_revalidation_hours": 0,
    "media_upload_max_size_mb": 50,
    "media_upload_allowed_types": [],
    "local_retention_days": 0,
    "remote_wipe_enabled": false,
    "version_id": "string"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

max_offline_duration_hoursinteger | null

Show child attributes

Any of

integer>= 0

null

force_revalidation_hoursinteger | null

Show child attributes

Any of

integer>= 0

null

media_upload_max_size_mbinteger | null

Show child attributes

Any of

integer[1, 500]

null

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger | null

Show child attributes

Any of

integer>= 0

null

remote_wipe_enabledboolean | null

Show child attributes

Any of

boolean

null

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_TenantDataGovernanceResponseDto

Successful Response

Response fields application/json

messagestringrequired

governanceBackend_TenantDataGovernanceDto | null

Show child attributes

Any of

idstring | null

Show child attributes

Any of

string

null

tenant_idstringrequired

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

version_idstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Delete Tenant Governance

DELETE

http://localhost:8000/api/v1/tenant-governance/{tenant_id}

Delete Tenant Governance

curl -X DELETE 'http://localhost:8000/api/v1/tenant-governance/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/tenant-governance/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8000/api/v1/tenant-governance/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "message": "string",
  "governance": {
    "id": "string",
    "tenant_id": "string",
    "max_offline_duration_hours": 0,
    "force_revalidation_hours": 0,
    "media_upload_max_size_mb": 50,
    "media_upload_allowed_types": [],
    "local_retention_days": 0,
    "remote_wipe_enabled": false,
    "version_id": "string"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKBackend_TenantDataGovernanceResponseDto

Successful Response

Response fields application/json

messagestringrequired

governanceBackend_TenantDataGovernanceDto | null

Show child attributes

Any of

idstring | null

Show child attributes

Any of

string

null

tenant_idstringrequired

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

version_idstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Create Tenant Governance

POST

http://localhost:8000/api/v1/tenant-governance

Create Tenant Governance

curl -X POST 'http://localhost:8000/api/v1/tenant-governance' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "tenant_id": "string",
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false
}'

const body = `{
  "tenant_id": "string",
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false
}`;

const response = await fetch('http://localhost:8000/api/v1/tenant-governance', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "tenant_id": "string",
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false
}'''

response = requests.post(
    'http://localhost:8000/api/v1/tenant-governance',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "tenant_id": "string",
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false
}

{
  "message": "string",
  "governance": {
    "id": "string",
    "tenant_id": "string",
    "max_offline_duration_hours": 0,
    "force_revalidation_hours": 0,
    "media_upload_max_size_mb": 50,
    "media_upload_allowed_types": [],
    "local_retention_days": 0,
    "remote_wipe_enabled": false,
    "version_id": "string"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

tenant_idstringrequired

max_offline_duration_hoursinteger>= 00

force_revalidation_hoursinteger>= 00

media_upload_max_size_mbinteger[1, 500]50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger>= 00

remote_wipe_enabledbooleanfalse

Response

201CreatedBackend_TenantDataGovernanceResponseDto

Successful Response

Response fields application/json

messagestringrequired

governanceBackend_TenantDataGovernanceDto | null

Show child attributes

Any of

idstring | null

Show child attributes

Any of

string

null

tenant_idstringrequired

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

version_idstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Issue Remote Wipe

POST

http://localhost:8000/api/v1/tenant-governance/{tenant_id}/remote-wipe

Issue Remote Wipe

curl -X POST 'http://localhost:8000/api/v1/tenant-governance/string/remote-wipe' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "target_user_id": "string",
  "reason": "string"
}'

const body = `{
  "target_user_id": "string",
  "reason": "string"
}`;

const response = await fetch('http://localhost:8000/api/v1/tenant-governance/string/remote-wipe', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "target_user_id": "string",
  "reason": "string"
}'''

response = requests.post(
    'http://localhost:8000/api/v1/tenant-governance/string/remote-wipe',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "target_user_id": "string",
  "reason": "string"
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Body

application/json

target_user_idstring | null

Show child attributes

Any of

string

null

reasonstring | null

Show child attributes

Any of

string

null

Parameters

tenant_idstringrequiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Backend / App Version

App Version — Backend

Get App Version

GET

http://localhost:8000/api/v1/app/version

Get App Version

curl -X GET 'http://localhost:8000/api/v1/app/version'

const response = await fetch('http://localhost:8000/api/v1/app/version', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8000/api/v1/app/version')
print(response.text)

200

{
  "latest_version": "2.1.0",
  "download_url": "https://releases.mquad.local/v2.1.0/mquad.apk",
  "checksum_sha256": "a1b2c3d4e5f6...",
  "min_version": "1.5.0",
  "release_notes": "Fixed sync conflicts, improved offline stability"
}

Response

200OKBackend_AppVersionCheckResponseDto

Successful Response

Response fields application/json

latest_versionstringrequired

Example

2.1.0

download_urlstring | null

Show child attributes

Any of

string

null

Example

https://releases.mquad.local/v2.1.0/mquad.apk

checksum_sha256string | null

Show child attributes

Any of

string

null

Example

a1b2c3d4e5f6...

min_versionstring | null

Show child attributes

Any of

string

null

Example

1.5.0

release_notesstring | null

Show child attributes

Any of

string

null

Example

Fixed sync conflicts, improved offline stability

Survey Service

Survey design, publishing, versioning, templates, question bank, languages, lookups, access

Upload XLSForm as New Survey Version

POST

http://localhost:8001/api/v1/surveys/{survey_id}/versions/upload

Create a new version of an existing survey by uploading an XLSForm file.

This endpoint:

Validates the uploaded file (size, extension)
Parses the XLSForm using XLSFormImportService
Validates schema using existing validators
Creates a new version using VersionService (SAME logic as JSON endpoint)
Returns standardized response

Upload XLSForm as New Survey Version

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/upload' \
  --form-string 'file=string'

const form = new FormData();
form.append('file', 'string');
const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/upload', {
  method: 'POST',
  headers: {},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('file', (None, 'string')),
    ]
    response = requests.request('POST', 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/upload', headers={}, files=files)
    print(response.text)

Request Body

{
  "file": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filestringrequired

Parameters

survey_idstring<uuid>requiredpath

Response

201Createdany

Created survey version

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Download blank form as PDF

GET

http://localhost:8001/api/v1/surveys/{survey_id}/blank.pdf

Generate and download a blank paper form PDF for a published survey.

Download blank form as PDF

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/blank.pdf?primary_language=en&secondary_language=&export_mode=single&version=&org='

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/blank.pdf?primary_language=en&secondary_language=&export_mode=single&version=&org=', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/blank.pdf?primary_language=en&secondary_language=&export_mode=single&version=&org=')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

primary_languagestringenquery

Primary language code for labels

secondary_languagestringquery

Secondary language code for bilingual mode

export_modestringsinglequery

Export mode: 'single' or 'bilingual'

langstringquery

(Deprecated) Use primary_language instead

versionstringquery

Version string (optional)

orgstringquery

Organization name (optional)

Response

200OKany

PDF file bytes

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Survey Service / Survey Tags

Survey Tags — Survey Service

List Tags

GET

http://localhost:8001/api/v1/surveys/tags

List all tags for the tenant.

List Tags

curl -X GET 'http://localhost:8001/api/v1/surveys/tags'

const response = await fetch('http://localhost:8001/api/v1/surveys/tags', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/tags')
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "total": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

searchstring | nullquery

Search tags by name

Response

200OKSurveyService_TagListResponse

Successful Response

Response fields application/json

itemsArray<SurveyService_TagResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

totalintegerrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Tag

POST

http://localhost:8001/api/v1/surveys/tags

Create a new tag.

Create Tag

curl -X POST 'http://localhost:8001/api/v1/surveys/tags' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "color": "string"
}'

const body = `{
  "name": "string",
  "color": "string"
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/tags', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "color": "string"
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/tags',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "color": "string"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "color": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

Response

201CreatedSurveyService_TagResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Tag

PUT

http://localhost:8001/api/v1/surveys/tags/{tag_id}

Update a tag.

Update Tag

curl -X PUT 'http://localhost:8001/api/v1/surveys/tags/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "color": "string"
}'

const body = `{
  "name": "string",
  "color": "string"
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/tags/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "color": "string"
}'''

response = requests.put(
    'http://localhost:8001/api/v1/surveys/tags/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "color": "string"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "color": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

Parameters

tag_idstring<uuid>requiredpath

Response

200OKSurveyService_TagResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Tag

DELETE

http://localhost:8001/api/v1/surveys/tags/{tag_id}

Delete a tag and remove all associations.

Delete Tag

curl -X DELETE 'http://localhost:8001/api/v1/surveys/tags/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8001/api/v1/surveys/tags/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8001/api/v1/surveys/tags/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

tag_idstring<uuid>requiredpath

Response

204No Content

Successful Response

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Survey Tags

GET

http://localhost:8001/api/v1/surveys/{survey_id}/tags

Get all tags assigned to a survey.

Get Survey Tags

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/tags'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/tags', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/tags')
print(response.text)

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string",
    "color": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "created_by": "550e8400-e29b-41d4-a716-446655440000"
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKArray<SurveyService_TagResponse>

Successful Response

Response fields application/json

Array<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Assign Tags To Survey

POST

http://localhost:8001/api/v1/surveys/{survey_id}/tags

Assign tags to a survey (replaces all existing tag assignments).

Assign Tags To Survey

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/tags' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "tag_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}'

const body = `{
  "tag_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/tags', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "tag_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/tags',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "tag_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "string",
    "color": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "created_by": "550e8400-e29b-41d4-a716-446655440000"
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

tag_idsArray<string>required

Parameters

survey_idstring<uuid>requiredpath

Response

200OKArray<SurveyService_TagResponse>

Successful Response

Response fields application/json

Array<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Survey Service / Languages

Languages — Survey Service

List Languages

GET

http://localhost:8001/api/v1/surveys/languages

List all languages for the tenant.

List Languages

curl -X GET 'http://localhost:8001/api/v1/surveys/languages?include_inactive=false'

const response = await fetch('http://localhost:8001/api/v1/surveys/languages?include_inactive=false', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/languages?include_inactive=false')
print(response.text)

{
  "languages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "string",
      "name": "string",
      "flag_emoji": "string",
      "is_active": true,
      "display_order": 0
    }
  ],
  "total": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

include_inactivebooleanfalsequery

Include inactive languages in the response

Response

200OKSurveyService_LanguageListResponse

Successful Response

Response fields application/json

languagesArray<SurveyService_LanguageResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

codestringrequired

namestringrequired

flag_emojistring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

display_orderintegerrequired

totalintegerrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Language

POST

http://localhost:8001/api/v1/surveys/languages

Create a new language for the tenant.

Create Language

curl -X POST 'http://localhost:8001/api/v1/surveys/languages' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "code": "string",
  "name": "string",
  "flag_emoji": "string",
  "is_active": true,
  "display_order": 0
}'

const body = `{
  "code": "string",
  "name": "string",
  "flag_emoji": "string",
  "is_active": true,
  "display_order": 0
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/languages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "code": "string",
  "name": "string",
  "flag_emoji": "string",
  "is_active": true,
  "display_order": 0
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/languages',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "code": "string",
  "name": "string",
  "flag_emoji": "string",
  "is_active": true,
  "display_order": 0
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "string",
  "name": "string",
  "flag_emoji": "string",
  "is_active": true,
  "display_order": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

codestringrequired

Language code (e.g., 'en', 'hi')

namestringrequired

Language name (e.g., 'English', 'Hindi')

flag_emojistring | null

Flag emoji (e.g., '🇺🇸')

Show child attributes

Any of

string

null

is_activebooleantrue

Whether language is active

display_orderinteger0

Display order for sorting

Response

201CreatedSurveyService_LanguageResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

codestringrequired

namestringrequired

flag_emojistring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

display_orderintegerrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Reorder Languages

PUT

http://localhost:8001/api/v1/surveys/languages/reorder

Reorder languages by updating display_order based on array position.

Reorder Languages

curl -X PUT 'http://localhost:8001/api/v1/surveys/languages/reorder' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "language_ids": [
    "string"
  ]
}'

const body = `{
  "language_ids": [
    "string"
  ]
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/languages/reorder', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "language_ids": [
    "string"
  ]
}'''

response = requests.put(
    'http://localhost:8001/api/v1/surveys/languages/reorder',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "language_ids": [
    "string"
  ]
}

{
  "languages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "string",
      "name": "string",
      "flag_emoji": "string",
      "is_active": true,
      "display_order": 0
    }
  ],
  "total": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

language_idsArray<string>required

List of language codes in desired order

Response

200OKSurveyService_LanguageListResponse

Successful Response

Response fields application/json

languagesArray<SurveyService_LanguageResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

codestringrequired

namestringrequired

flag_emojistring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

display_orderintegerrequired

totalintegerrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Language

PUT

http://localhost:8001/api/v1/surveys/languages/{language_id}

Update an existing language.

Update Language

curl -X PUT 'http://localhost:8001/api/v1/surveys/languages/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "code": "string",
  "name": "string",
  "flag_emoji": "string",
  "is_active": true,
  "display_order": 0
}'

const body = `{
  "code": "string",
  "name": "string",
  "flag_emoji": "string",
  "is_active": true,
  "display_order": 0
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/languages/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "code": "string",
  "name": "string",
  "flag_emoji": "string",
  "is_active": true,
  "display_order": 0
}'''

response = requests.put(
    'http://localhost:8001/api/v1/surveys/languages/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "code": "string",
  "name": "string",
  "flag_emoji": "string",
  "is_active": true,
  "display_order": 0
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "string",
  "name": "string",
  "flag_emoji": "string",
  "is_active": true,
  "display_order": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

codestring | null

Show child attributes

Any of

string

null

namestring | null

Show child attributes

Any of

string

null

flag_emojistring | null

Show child attributes

Any of

string

null

is_activeboolean | null

Show child attributes

Any of

boolean

null

display_orderinteger | null

Show child attributes

Any of

integer

null

Parameters

language_idstring<uuid>requiredpath

Response

200OKSurveyService_LanguageResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

codestringrequired

namestringrequired

flag_emojistring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

display_orderintegerrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Language

DELETE

http://localhost:8001/api/v1/surveys/languages/{language_id}

Hard delete a language (remove from database).

Delete Language

curl -X DELETE 'http://localhost:8001/api/v1/surveys/languages/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8001/api/v1/surveys/languages/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8001/api/v1/surveys/languages/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

language_idstring<uuid>requiredpath

Response

204No Content

Successful Response

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Seed Default Languages

POST

http://localhost:8001/api/v1/surveys/languages/seed

Seed default languages for the tenant (if none exist).

Seed Default Languages

curl -X POST 'http://localhost:8001/api/v1/surveys/languages/seed'

const response = await fetch('http://localhost:8001/api/v1/surveys/languages/seed', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/surveys/languages/seed')
print(response.text)

200

{
  "languages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "string",
      "name": "string",
      "flag_emoji": "string",
      "is_active": true,
      "display_order": 0
    }
  ],
  "total": 0
}

Response

200OKSurveyService_LanguageListResponse

Successful Response

Response fields application/json

languagesArray<SurveyService_LanguageResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

codestringrequired

namestringrequired

flag_emojistring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

display_orderintegerrequired

totalintegerrequired

Survey Service / Lookups

Lookups — Survey Service

Resolve lookup values

POST

http://localhost:8001/api/v1/surveys/lookups/{survey_id}/resolve

Resolve dependent field values based on a trigger question and value

Resolve lookup values

curl -X POST 'http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/resolve' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "trigger_question": "string",
  "trigger_value": "string",
  "current_values": {}
}'

const body = `{
  "trigger_question": "string",
  "trigger_value": "string",
  "current_values": {}
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/resolve', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "trigger_question": "string",
  "trigger_value": "string",
  "current_values": {}
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/resolve',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "trigger_question": "string",
  "trigger_value": "string",
  "current_values": {}
}

{
  "trigger_question": "string",
  "trigger_value": "string",
  "resolved_values": {},
  "fields_to_clear": [
    "string"
  ],
  "is_valid": true,
  "error_message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request model for lookup resolution.

trigger_questionstringrequired

Name of the trigger question

trigger_valuestringrequired

Selected value for the trigger question

current_valuesobject | null

Current values of all questions (for change detection)

Show child attributes

Any of

object

null

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_LookupResolveResponse

Successful Response

Response fields application/json

Response model for lookup resolution.

trigger_questionstringrequired

trigger_valuestringrequired

resolved_valuesobjectrequired

fields_to_clearArray<string>

is_validbooleantrue

error_messagestring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Validate lookup value

POST

http://localhost:8001/api/v1/surveys/lookups/{survey_id}/validate

Validate that a lookup value exists in the lookup data

Validate lookup value

curl -X POST 'http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/validate' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "trigger_question": "string",
  "trigger_value": "string"
}'

const body = `{
  "trigger_question": "string",
  "trigger_value": "string"
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/validate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "trigger_question": "string",
  "trigger_value": "string"
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/validate',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "trigger_question": "string",
  "trigger_value": "string"
}

{
  "is_valid": true,
  "trigger_question": "string",
  "trigger_value": "string",
  "error_message": "string",
  "available_values": [
    "string"
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request model for lookup validation.

trigger_questionstringrequired

Name of the trigger question

trigger_valuestringrequired

Value to validate

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_LookupValidateResponse

Successful Response

Response fields application/json

Response model for lookup validation.

is_validbooleanrequired

trigger_questionstringrequired

trigger_valuestringrequired

error_messagestring | null

Show child attributes

Any of

string

null

available_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get lookup configuration

GET

http://localhost:8001/api/v1/surveys/lookups/{survey_id}/config

Get structured lookup configuration for a survey

Get lookup configuration

curl -X GET 'http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/config'

const response = await fetch('http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/config', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/config')
print(response.text)

{
  "has_lookups": true,
  "lookup_keys": [
    {}
  ],
  "trigger_questions": [
    "string"
  ],
  "referee_questions": {}
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_LookupConfigResponse

Successful Response

Response fields application/json

Response model for lookup configuration.

has_lookupsbooleanrequired

lookup_keysArray<object>required

trigger_questionsArray<string>required

referee_questionsobjectrequired

Show child attributes

[key: string]Array<string>

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get all lookup values

GET

http://localhost:8001/api/v1/surveys/lookups/{survey_id}/values/{trigger_question}

Get all valid values for a trigger question

Get all lookup values

curl -X GET 'http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/values/string'

const response = await fetch('http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/values/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/values/string')
print(response.text)

[
  "string"
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

trigger_questionstringrequiredpath

Response

200OKArray<string>

Successful Response

Response fields application/json

Array<string>

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get lookup statistics

GET

http://localhost:8001/api/v1/surveys/lookups/{survey_id}/statistics

Get statistics about lookup data

Get lookup statistics

curl -X GET 'http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/statistics'

const response = await fetch('http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/statistics', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/statistics')
print(response.text)

{
  "trigger_questions": 0,
  "total_values": 0,
  "trigger_details": {}
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_LookupStatisticsResponse

Successful Response

Response fields application/json

Response model for lookup statistics.

trigger_questionsintegerrequired

total_valuesintegerrequired

trigger_detailsobjectrequired

Show child attributes

[key: string]object

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get available trigger values

GET

http://localhost:8001/api/v1/surveys/lookups/{survey_id}/available-triggers

Get trigger values with availability status for assignment UI

Get available trigger values

curl -X GET 'http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/available-triggers'

const response = await fetch('http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/available-triggers', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/lookups/550e8400-e29b-41d4-a716-446655440000/available-triggers')
print(response.text)

{
  "trigger_questions": [
    "string"
  ],
  "available_values": {},
  "assigned_values": {}
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_AvailableTriggersResponse

Successful Response

Response fields application/json

Response model for available trigger values with assignment info.

trigger_questionsArray<string>required

available_valuesobjectrequired

Show child attributes

[key: string]Array<string>

assigned_valuesobjectrequired

Show child attributes

[key: string]object

Show child attributes

[key: string]string | null

Show child attributes

Any of

string

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Survey Service / Question Bank

Question Bank — Survey Service

List Categories

GET

http://localhost:8001/api/v1/surveys/question-bank/categories

List question bank categories. Permission: template:read or template:manage

List Categories

curl -X GET 'http://localhost:8001/api/v1/surveys/question-bank/categories?skip=0&limit=20'

const response = await fetch('http://localhost:8001/api/v1/surveys/question-bank/categories?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/question-bank/categories?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "name": "string",
      "description": "string",
      "color": "string",
      "question_count": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "skip": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

searchstring | nullquery

Search categories by name or description

Response

200OKSurveyService_QuestionBankCategoryListResponse

Successful Response

Response fields application/json

itemsArray<SurveyService_QuestionBankCategoryResponse>required

Show child attributes

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

question_countinteger0

created_atstring<date-time>required

updated_atstring<date-time>required

totalintegerrequired

limitintegerrequired

skipintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Category

POST

http://localhost:8001/api/v1/surveys/question-bank/categories

Create category. Permission: template:create or template:manage

Create Category

curl -X POST 'http://localhost:8001/api/v1/surveys/question-bank/categories' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "color": "string"
}'

const body = `{
  "name": "string",
  "description": "string",
  "color": "string"
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/question-bank/categories', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "color": "string"
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/question-bank/categories',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "color": "string"
}

{
  "id": "string",
  "tenant_id": "string",
  "name": "string",
  "description": "string",
  "color": "string",
  "question_count": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

Response

201CreatedSurveyService_QuestionBankCategoryResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

question_countinteger0

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Category

PUT

http://localhost:8001/api/v1/surveys/question-bank/categories/{category_id}

Update category. Permission: template:update or template:manage

Update Category

curl -X PUT 'http://localhost:8001/api/v1/surveys/question-bank/categories/string' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "color": "string"
}'

const body = `{
  "name": "string",
  "description": "string",
  "color": "string"
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/question-bank/categories/string', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "color": "string"
}'''

response = requests.put(
    'http://localhost:8001/api/v1/surveys/question-bank/categories/string',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "color": "string"
}

{
  "id": "string",
  "tenant_id": "string",
  "name": "string",
  "description": "string",
  "color": "string",
  "question_count": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

Parameters

category_idstringrequiredpath

Response

200OKSurveyService_QuestionBankCategoryResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

question_countinteger0

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Category

DELETE

http://localhost:8001/api/v1/surveys/question-bank/categories/{category_id}

Delete category. Permission: template:delete or template:manage

Delete Category

curl -X DELETE 'http://localhost:8001/api/v1/surveys/question-bank/categories/string'

const response = await fetch('http://localhost:8001/api/v1/surveys/question-bank/categories/string', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8001/api/v1/surveys/question-bank/categories/string')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

category_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

List Questions

GET

http://localhost:8001/api/v1/surveys/question-bank/questions

List/search reusable questions. Permission: template:create or survey:create or template:manage or survey:manage

List Questions

curl -X GET 'http://localhost:8001/api/v1/surveys/question-bank/questions?skip=0&limit=20'

const response = await fetch('http://localhost:8001/api/v1/surveys/question-bank/questions?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/question-bank/questions?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "category_id": "string",
      "question_type": "string",
      "name": "string",
      "label": "string",
      "label_translations": {},
      "hint": "string",
      "hint_translations": {},
      "required": true,
      "question_config": {},
      "tags": [
        "string"
      ],
      "usage_count": 0,
      "is_public": true,
      "created_by": "string",
      "updated_by": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "category": {
        "id": "string",
        "tenant_id": "string",
        "name": "string",
        "description": "string",
        "color": "string",
        "question_count": 0,
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    }
  ],
  "total": 0,
  "limit": 0,
  "skip": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

category_idstring | nullquery

Filter questions by category

question_typestring | nullquery

Filter questions by type

searchstring | nullquery

Search questions by name or label

tagsstring | nullquery

Filter questions by tags

Response

200OKSurveyService_QuestionListResponse

Successful Response

Response fields application/json

itemsArray<SurveyService_QuestionResponse>required

Show child attributes

idstringrequired

tenant_idstringrequired

category_idstring | null

Show child attributes

Any of

string

null

question_typestringrequired

namestringrequired

labelstringrequired

label_translationsobjectrequired

Show child attributes

[key: string]string

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobjectrequired

Show child attributes

[key: string]string

requiredbooleanrequired

question_configobjectrequired

tagsArray<string>required

usage_countintegerrequired

is_publicbooleanrequired

created_bystringrequired

updated_bystring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_QuestionBankCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

question_countinteger0

created_atstring<date-time>required

updated_atstring<date-time>required

null

totalintegerrequired

limitintegerrequired

skipintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Question

POST

http://localhost:8001/api/v1/surveys/question-bank/questions

Create a reusable question. Permission: template:create or template:manage

Create Question

curl -X POST 'http://localhost:8001/api/v1/surveys/question-bank/questions' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "category_id": "string",
  "question_type": "string",
  "name": "string",
  "label": "",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": false,
  "question_config": {},
  "tags": [
    "string"
  ],
  "is_public": false
}'

const body = `{
  "category_id": "string",
  "question_type": "string",
  "name": "string",
  "label": "",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": false,
  "question_config": {},
  "tags": [
    "string"
  ],
  "is_public": false
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/question-bank/questions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "category_id": "string",
  "question_type": "string",
  "name": "string",
  "label": "",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": false,
  "question_config": {},
  "tags": [
    "string"
  ],
  "is_public": false
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/question-bank/questions',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "category_id": "string",
  "question_type": "string",
  "name": "string",
  "label": "",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": false,
  "question_config": {},
  "tags": [
    "string"
  ],
  "is_public": false
}

{
  "id": "string",
  "tenant_id": "string",
  "category_id": "string",
  "question_type": "string",
  "name": "string",
  "label": "string",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": true,
  "question_config": {},
  "tags": [
    "string"
  ],
  "usage_count": 0,
  "is_public": true,
  "created_by": "string",
  "updated_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "color": "string",
    "question_count": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

category_idstring | null

Show child attributes

Any of

string

null

question_typestringrequired

namestringrequired

labelstring

label_translationsobject

Show child attributes

[key: string]string

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject

Show child attributes

[key: string]string

requiredbooleanfalse

question_configobject

tagsArray<string>

is_publicbooleanfalse

Response

201CreatedSurveyService_QuestionResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstringrequired

category_idstring | null

Show child attributes

Any of

string

null

question_typestringrequired

namestringrequired

labelstringrequired

label_translationsobjectrequired

Show child attributes

[key: string]string

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobjectrequired

Show child attributes

[key: string]string

requiredbooleanrequired

question_configobjectrequired

tagsArray<string>required

usage_countintegerrequired

is_publicbooleanrequired

created_bystringrequired

updated_bystring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_QuestionBankCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

question_countinteger0

created_atstring<date-time>required

updated_atstring<date-time>required

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Question

GET

http://localhost:8001/api/v1/surveys/question-bank/questions/{question_id}

Get question details. Permission: template:create or survey:create or template:manage or survey:manage

Get Question

curl -X GET 'http://localhost:8001/api/v1/surveys/question-bank/questions/string'

const response = await fetch('http://localhost:8001/api/v1/surveys/question-bank/questions/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/question-bank/questions/string')
print(response.text)

{
  "id": "string",
  "tenant_id": "string",
  "category_id": "string",
  "question_type": "string",
  "name": "string",
  "label": "string",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": true,
  "question_config": {},
  "tags": [
    "string"
  ],
  "usage_count": 0,
  "is_public": true,
  "created_by": "string",
  "updated_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "color": "string",
    "question_count": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

question_idstringrequiredpath

Response

200OKSurveyService_QuestionResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstringrequired

category_idstring | null

Show child attributes

Any of

string

null

question_typestringrequired

namestringrequired

labelstringrequired

label_translationsobjectrequired

Show child attributes

[key: string]string

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobjectrequired

Show child attributes

[key: string]string

requiredbooleanrequired

question_configobjectrequired

tagsArray<string>required

usage_countintegerrequired

is_publicbooleanrequired

created_bystringrequired

updated_bystring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_QuestionBankCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

question_countinteger0

created_atstring<date-time>required

updated_atstring<date-time>required

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Question

PUT

http://localhost:8001/api/v1/surveys/question-bank/questions/{question_id}

Update a reusable question. Permission: template:update or template:manage

Update Question

curl -X PUT 'http://localhost:8001/api/v1/surveys/question-bank/questions/string' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "category_id": "string",
  "label": "string",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": true,
  "question_config": {},
  "tags": [
    "string"
  ],
  "is_public": true
}'

const body = `{
  "category_id": "string",
  "label": "string",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": true,
  "question_config": {},
  "tags": [
    "string"
  ],
  "is_public": true
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/question-bank/questions/string', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "category_id": "string",
  "label": "string",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": true,
  "question_config": {},
  "tags": [
    "string"
  ],
  "is_public": true
}'''

response = requests.put(
    'http://localhost:8001/api/v1/surveys/question-bank/questions/string',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "category_id": "string",
  "label": "string",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": true,
  "question_config": {},
  "tags": [
    "string"
  ],
  "is_public": true
}

{
  "id": "string",
  "tenant_id": "string",
  "category_id": "string",
  "question_type": "string",
  "name": "string",
  "label": "string",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": true,
  "question_config": {},
  "tags": [
    "string"
  ],
  "usage_count": 0,
  "is_public": true,
  "created_by": "string",
  "updated_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "color": "string",
    "question_count": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

category_idstring | null

Show child attributes

Any of

string

null

labelstring | null

Show child attributes

Any of

string

null

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredboolean | null

Show child attributes

Any of

boolean

null

question_configobject | null

Show child attributes

Any of

object

null

tagsArray<string> | null

Show child attributes

Any of

Array<string>

null

is_publicboolean | null

Show child attributes

Any of

boolean

null

Parameters

question_idstringrequiredpath

Response

200OKSurveyService_QuestionResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstringrequired

category_idstring | null

Show child attributes

Any of

string

null

question_typestringrequired

namestringrequired

labelstringrequired

label_translationsobjectrequired

Show child attributes

[key: string]string

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobjectrequired

Show child attributes

[key: string]string

requiredbooleanrequired

question_configobjectrequired

tagsArray<string>required

usage_countintegerrequired

is_publicbooleanrequired

created_bystringrequired

updated_bystring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_QuestionBankCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

question_countinteger0

created_atstring<date-time>required

updated_atstring<date-time>required

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Question

DELETE

http://localhost:8001/api/v1/surveys/question-bank/questions/{question_id}

Delete a reusable question. Permission: template:delete or template:manage

Delete Question

curl -X DELETE 'http://localhost:8001/api/v1/surveys/question-bank/questions/string'

const response = await fetch('http://localhost:8001/api/v1/surveys/question-bank/questions/string', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8001/api/v1/surveys/question-bank/questions/string')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

question_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Import Questions

POST

http://localhost:8001/api/v1/surveys/question-bank/questions/import

Import multiple questions from a CSV file.

Expected header: type,name,label,hint,required,tags. Valid rows are created and invalid rows are skipped with per-row errors (partial success). Permission: template:create or template:manage

Import Questions

curl -X POST 'http://localhost:8001/api/v1/surveys/question-bank/questions/import' \
  --form-string 'file=string' \
  --form-string 'category_id=string'

const form = new FormData();
form.append('file', 'string');
form.append('category_id', 'string');
const response = await fetch('http://localhost:8001/api/v1/surveys/question-bank/questions/import', {
  method: 'POST',
  headers: {},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('file', (None, 'string')),
        ('category_id', (None, 'string')),
    ]
    response = requests.request('POST', 'http://localhost:8001/api/v1/surveys/question-bank/questions/import', headers={}, files=files)
    print(response.text)

Request Body

{
  "file": "string",
  "category_id": "string"
}

{
  "total": 0,
  "created": 0,
  "failed": 0,
  "errors": [
    {
      "row": 0,
      "field": "",
      "code": "string",
      "message": "string"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filestringrequired

category_idstring | null

Show child attributes

Any of

string

null

Response

200OKSurveyService_QuestionBulkImportResponse

Successful Response

Response fields application/json

totalintegerrequired

createdintegerrequired

failedintegerrequired

errorsArray<SurveyService_QuestionImportRowError>

Show child attributes

rowintegerrequired

fieldstring

codestringrequired

messagestringrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Add Question To Survey

POST

http://localhost:8001/api/v1/surveys/question-bank/add-to-survey

Add a bank question to a survey's schema. Permission: survey:create or survey:manage

Returns the full question JSON object that the frontend can directly insert into the survey schema.

Add Question To Survey

curl -X POST 'http://localhost:8001/api/v1/surveys/question-bank/add-to-survey' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "question_id": "string",
  "survey_id": "string"
}'

const body = `{
  "question_id": "string",
  "survey_id": "string"
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/question-bank/add-to-survey', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "question_id": "string",
  "survey_id": "string"
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/question-bank/add-to-survey',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "question_id": "string",
  "survey_id": "string"
}

{
  "survey_id": "string",
  "question_id": "string",
  "question_name": "string",
  "question": {}
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

question_idstringrequired

survey_idstringrequired

Response

200OKSurveyService_AddQuestionToSurveyResponse

Successful Response

Response fields application/json

survey_idstringrequired

question_idstringrequired

question_namestringrequired

questionobjectrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Survey Service / Surveys

Surveys — Survey Service

List Surveys

GET

http://localhost:8001/api/v1/surveys

List surveys for the tenant.

Admin users (with survey:manage/survey:read) see all surveys in the tenant
Non-admin users only see surveys they have explicit access to via form_access table
Internal callers (sync-service) can pass filter_user_id to force form_access filtering for a specific user, regardless of caller permissions

List Surveys

curl -X GET 'http://localhost:8001/api/v1/surveys?skip=0&limit=20'

const response = await fetch('http://localhost:8001/api/v1/surveys?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "description": "string",
      "status": "string",
      "is_anonymous": true,
      "allow_multiple_responses": true,
      "survey_code": 0,
      "tags": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "string",
          "color": "string",
          "created_at": "2024-01-15T09:30:00Z",
          "updated_at": "2024-01-15T09:30:00Z",
          "created_by": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000",
      "closed_at": "2024-01-15T09:30:00Z",
      "open_at": "2024-01-15T09:30:00Z",
      "close_at": "2024-01-15T09:30:00Z",
      "scheduling_enabled": false,
      "is_open": false,
      "schema": {
        "settings": {},
        "choices": [
          {}
        ],
        "questions": [
          {
            "type": "string",
            "name": "string",
            "label": "string",
            "label_translations": {},
            "required": false,
            "hint": "string",
            "hint_translations": {},
            "default": "string",
            "order_index": 0,
            "additional_values": [
              "string"
            ],
            "read_only": false,
            "appearance": "string",
            "relevant": "string",
            "constraint": "string",
            "constraint_message": "string",
            "constraint_message_translations": {},
            "calculation": "string",
            "choices": "string",
            "choice_filter": "string",
            "choice_relation": "string",
            "repeat_count": "string",
            "questions": [],
            "limit": {},
            "paradata": [
              "string"
            ],
            "media_file": "string",
            "deidentify": false,
            "unique_id": false,
            "lookups": "string",
            "calendar_config": {},
            "calendar_rules": [
              {}
            ],
            "columns": [
              {}
            ]
          }
        ],
        "lookups": [
          {
            "lookup_name": "string",
            "key": "string",
            "value": "string",
            "parent_key": "string",
            "extra_data": {}
          }
        ],
        "lookup_data": [
          {}
        ]
      },
      "project_status": "string",
      "project_has_production_activity": true,
      "project_production_activity_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "skip": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

status_filterSurveyService_SurveyStatus | nullquery

project_idstring | nullquery

Filter surveys by project

searchstring | nullquery

Search surveys by name or description

tag_idstring | nullquery

Filter surveys by tag

workspace_idstring | nullquery

Filter surveys by workspace

updated_afterstring | nullquery

Only surveys updated after this timezone-aware instant

filter_user_idstring | nullquery

Filter by user ID (forced form_access check for internal callers like sync-service)

Response

200OKSurveyService_SurveyListResponse

Successful Response

Response fields application/json

itemsArray<SurveyService_SurveyResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

totalintegerrequired

limitintegerrequired

skipintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Survey

POST

http://localhost:8001/api/v1/surveys

Create a new survey.

Requires project_id which must be verified against workspace-service. Enforces survey.max_surveys limit via plan-enforcement-sdk.

Create Survey

curl -X POST 'http://localhost:8001/api/v1/surveys' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "schema": {
    "settings": {
      "form_title": "string",
      "form_id": "string",
      "version": "string",
      "defaultLanguage": "en",
      "languages": [
        "string"
      ],
      "availableLanguages": [
        "string"
      ],
      "instanceName": "string",
      "submissionUrl": "string"
    },
    "choices": [
      {
        "list_name": "string",
        "name": "string",
        "label": "string",
        "labelTranslations": {},
        "media_file": "string",
        "constraint": "string"
      }
    ],
    "questions": [
      {
        "type": "text",
        "name": "string",
        "label": "",
        "required": false,
        "hint": "string",
        "labelTranslations": {},
        "hintTranslations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraintMessageTranslations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "calendar_config": {
          "mode": "monthly",
          "months_back": 12,
          "start_from": "today",
          "allow_future": false
        },
        "calendar_rules": [
          {
            "id": "string",
            "trigger_question": "string",
            "target_column": "string",
            "value_source": "constant",
            "source_value": "string",
            "backfill_months": 1,
            "backfill_anchor": "current_month",
            "map_values": {},
            "xpath_expression": "string",
            "enabled": true,
            "conditions": [
              {}
            ],
            "months_scope": {}
          }
        ],
        "columns": [
          {
            "key": "string",
            "type": "select_one",
            "label": "",
            "label_translations": {},
            "choices": [
              {}
            ],
            "relevant": "string"
          }
        ],
        "limit": {
          "min": 0,
          "max": 0
        },
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "mediaAudio": "string",
        "mediaAudioSchema": {},
        "mediaAudioUrl": "string",
        "mediaAudioAssetId": "string",
        "mediaAudioUrlSchema": {},
        "mediaAudioAssetIdSchema": {},
        "deidentify": false,
        "unique_id": false,
        "lookups": "string"
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false
}'

const body = `{
  "name": "string",
  "description": "string",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "schema": {
    "settings": {
      "form_title": "string",
      "form_id": "string",
      "version": "string",
      "defaultLanguage": "en",
      "languages": [
        "string"
      ],
      "availableLanguages": [
        "string"
      ],
      "instanceName": "string",
      "submissionUrl": "string"
    },
    "choices": [
      {
        "list_name": "string",
        "name": "string",
        "label": "string",
        "labelTranslations": {},
        "media_file": "string",
        "constraint": "string"
      }
    ],
    "questions": [
      {
        "type": "text",
        "name": "string",
        "label": "",
        "required": false,
        "hint": "string",
        "labelTranslations": {},
        "hintTranslations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraintMessageTranslations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "calendar_config": {
          "mode": "monthly",
          "months_back": 12,
          "start_from": "today",
          "allow_future": false
        },
        "calendar_rules": [
          {
            "id": "string",
            "trigger_question": "string",
            "target_column": "string",
            "value_source": "constant",
            "source_value": "string",
            "backfill_months": 1,
            "backfill_anchor": "current_month",
            "map_values": {},
            "xpath_expression": "string",
            "enabled": true,
            "conditions": [
              {}
            ],
            "months_scope": {}
          }
        ],
        "columns": [
          {
            "key": "string",
            "type": "select_one",
            "label": "",
            "label_translations": {},
            "choices": [
              {}
            ],
            "relevant": "string"
          }
        ],
        "limit": {
          "min": 0,
          "max": 0
        },
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "mediaAudio": "string",
        "mediaAudioSchema": {},
        "mediaAudioUrl": "string",
        "mediaAudioAssetId": "string",
        "mediaAudioUrlSchema": {},
        "mediaAudioAssetIdSchema": {},
        "deidentify": false,
        "unique_id": false,
        "lookups": "string"
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "schema": {
    "settings": {
      "form_title": "string",
      "form_id": "string",
      "version": "string",
      "defaultLanguage": "en",
      "languages": [
        "string"
      ],
      "availableLanguages": [
        "string"
      ],
      "instanceName": "string",
      "submissionUrl": "string"
    },
    "choices": [
      {
        "list_name": "string",
        "name": "string",
        "label": "string",
        "labelTranslations": {},
        "media_file": "string",
        "constraint": "string"
      }
    ],
    "questions": [
      {
        "type": "text",
        "name": "string",
        "label": "",
        "required": false,
        "hint": "string",
        "labelTranslations": {},
        "hintTranslations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraintMessageTranslations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "calendar_config": {
          "mode": "monthly",
          "months_back": 12,
          "start_from": "today",
          "allow_future": false
        },
        "calendar_rules": [
          {
            "id": "string",
            "trigger_question": "string",
            "target_column": "string",
            "value_source": "constant",
            "source_value": "string",
            "backfill_months": 1,
            "backfill_anchor": "current_month",
            "map_values": {},
            "xpath_expression": "string",
            "enabled": true,
            "conditions": [
              {}
            ],
            "months_scope": {}
          }
        ],
        "columns": [
          {
            "key": "string",
            "type": "select_one",
            "label": "",
            "label_translations": {},
            "choices": [
              {}
            ],
            "relevant": "string"
          }
        ],
        "limit": {
          "min": 0,
          "max": 0
        },
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "mediaAudio": "string",
        "mediaAudioSchema": {},
        "mediaAudioUrl": "string",
        "mediaAudioAssetId": "string",
        "mediaAudioUrlSchema": {},
        "mediaAudioAssetIdSchema": {},
        "deidentify": false,
        "unique_id": false,
        "lookups": "string"
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "schema": {
    "settings": {
      "form_title": "string",
      "form_id": "string",
      "version": "string",
      "defaultLanguage": "en",
      "languages": [
        "string"
      ],
      "availableLanguages": [
        "string"
      ],
      "instanceName": "string",
      "submissionUrl": "string"
    },
    "choices": [
      {
        "list_name": "string",
        "name": "string",
        "label": "string",
        "labelTranslations": {},
        "media_file": "string",
        "constraint": "string"
      }
    ],
    "questions": [
      {
        "type": "text",
        "name": "string",
        "label": "",
        "required": false,
        "hint": "string",
        "labelTranslations": {},
        "hintTranslations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraintMessageTranslations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "calendar_config": {
          "mode": "monthly",
          "months_back": 12,
          "start_from": "today",
          "allow_future": false
        },
        "calendar_rules": [
          {
            "id": "string",
            "trigger_question": "string",
            "target_column": "string",
            "value_source": "constant",
            "source_value": "string",
            "backfill_months": 1,
            "backfill_anchor": "current_month",
            "map_values": {},
            "xpath_expression": "string",
            "enabled": true,
            "conditions": [
              {}
            ],
            "months_scope": {}
          }
        ],
        "columns": [
          {
            "key": "string",
            "type": "select_one",
            "label": "",
            "label_translations": {},
            "choices": [
              {}
            ],
            "relevant": "string"
          }
        ],
        "limit": {
          "min": 0,
          "max": 0
        },
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "mediaAudio": "string",
        "mediaAudioSchema": {},
        "mediaAudioUrl": "string",
        "mediaAudioAssetId": "string",
        "mediaAudioUrlSchema": {},
        "mediaAudioAssetIdSchema": {},
        "deidentify": false,
        "unique_id": false,
        "lookups": "string"
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "survey_code": 0,
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "closed_at": "2024-01-15T09:30:00Z",
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false,
  "is_open": false,
  "schema": {
    "settings": {},
    "choices": [
      {}
    ],
    "questions": [
      {
        "type": "string",
        "name": "string",
        "label": "string",
        "label_translations": {},
        "required": false,
        "hint": "string",
        "hint_translations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraint_message_translations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "limit": {},
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "deidentify": false,
        "unique_id": false,
        "lookups": "string",
        "calendar_config": {},
        "calendar_rules": [
          {}
        ],
        "columns": [
          {}
        ]
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "project_status": "string",
  "project_has_production_activity": true,
  "project_production_activity_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

is_anonymousbooleanfalse

allow_multiple_responsesbooleanfalse

schemaSurveyService_SurveySchema | null

Show child attributes

Any of

Complete XLSForm-compatible survey schema. Stored in JSONB column in survey_versions table. Includes support for custom lookups worksheet for cascading selects.

Note: 'title', 'version', 'description' and 'id' fields are accepted for backwards compatibility with frontend schema transformations but are not required for storage (they're derived from the survey/version metadata).

settingsSurveyService_SettingsSchemarequired

Survey-level settings (XLSForm settings sheet)

Show child attributes

form_titlestringrequired

form_idstring | null

Show child attributes

Any of

string

null

versionstring | null

Show child attributes

Any of

string

null

defaultLanguagestring | nullen

Show child attributes

Any of

string

null

languagesArray<string> | null

Show child attributes

Any of

Array<string>

null

availableLanguagesArray<string> | null

Show child attributes

Any of

Array<string>

null

instanceNamestring | null

Show child attributes

Any of

string

null

submissionUrlstring | null

Show child attributes

Any of

string

null

choicesArray<SurveyService_ChoiceSchema>

Show child attributes

Choice list item (XLSForm choices sheet)

list_namestringrequired

namestringrequired

labelstringrequired

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

media_filestring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionSchema>required

Show child attributes

XLSForm-compatible question schema. Supports all 22 question types with recursive nesting for groups/repeats.

typeSurveyService_SurveyQuestionTypetextintegerdecimalrangeselect_oneselect_multiplerankdatetimedatetimegeopointgeotracegeoshapeimageaudiovideofilebarcodesignaturecalculatenotehiddenacknowledgetriggerurlphonestartendtodaydeviceidphonenumberusernameemailsimserialsubscriberidauditxml-externalcsv-externalbegin_groupend_groupbegin_repeatend_repeatcalendar_gridrequired

Complete XLSForm-compatible question types (KoboToolbox standard). Reference: https://xlsform.org/en/#question-types

namestringrequired

labelstring

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

hintTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraintMessageTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | null

Show child attributes

Any of

string

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionSchema> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionSchema>

null

calendar_configSurveyService_CalendarConfigSchema | null

Show child attributes

Any of

Configuration for calendar_grid question type

modestringmonthly

months_backinteger[1, 120]12

start_fromstringtoday

allow_futurebooleanfalse

null

calendar_rulesArray<SurveyService_CalendarRuleSchema> | null

Auto-prefill rules for calendar columns

Show child attributes

Any of

Array<SurveyService_CalendarRuleSchema>

Show child attributes

Rule for auto-prefilling calendar column values

idstring | null

Unique rule ID

Show child attributes

Any of

string

null

trigger_questionstringrequired

Question name that triggers this rule

target_columnstringrequired

Calendar column key to fill

value_sourcestringconstant

Where to get the value: constant, lookup, or xpath expression

source_valuestring | null

Constant value to fill (for constant source)

Show child attributes

Any of

string

null

backfill_monthsinteger | null1

How many months to backfill from anchor

Show child attributes

Any of

integer[1, 120]

null

backfill_anchorstring | SurveyService_BackfillAnchorSchema | nullcurrent_month

Anchor for backfill: 'current_month', or anchor config object

Show child attributes

Any of

string

Anchor configuration for timeline-aware backfill

typestringrequired

Anchor type

questionstring | null

Question name (for from_answer_month type)

Show child attributes

Any of

Max depth reached

rule_idstring | null

Rule ID to anchor to (for before_rule/after_rule types)

Show child attributes

Any of

Max depth reached

null

map_valuesobject | null

Map trigger values to calendar values (e.g., {'yes': 'Y', 'no': 'N'})

Show child attributes

Any of

[key: string]string

null

xpath_expressionstring | null

XPath expression to calculate value (for xpath source)

Show child attributes

Any of

string

null

enabledbooleantrue

Whether rule is active

conditionsArray<object> | null

Conditions for when the rule applies (Visual Rule Builder)

Show child attributes

Any of

Array<object>

null

months_scopeobject | null

Months scope configuration for the rule

Show child attributes

Any of

object

null

columnsArray<SurveyService_CalendarColumnSchema> | null

Show child attributes

Any of

Array<SurveyService_CalendarColumnSchema>

Show child attributes

Column definition for calendar_grid question type

keystringrequired

typestringselect_one

labelstring

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

choicesArray<object> | null

Choices for select_one type - name must be exactly 1 character

Show child attributes

Any of

Array<object>

null

relevantstring | null

Show child attributes

Any of

string

null

limitSurveyService_LimitSchema | null

Show child attributes

Any of

Limit configuration for text/number fields. For text: min/max character count For integer/decimal: min/max value

mininteger | null

Show child attributes

Any of

integer

null

maxinteger | null

Show child attributes

Any of

integer

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

mediaAudiostring | null

Show child attributes

Any of

string

null

mediaAudioSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioUrlstring | null

Show child attributes

Any of

string

null

mediaAudioAssetIdstring | null

Show child attributes

Any of

string

null

mediaAudioUrlSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioAssetIdSchemaobject | null

Show child attributes

Any of

[key: string]string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

lookupsArray<SurveyService_LookupSchema>

Show child attributes

Lookup data item (custom lookups worksheet). Used for cascading selects and external data lookups.

Example:

lookup_name: "countries" or "states"
key: "us" or "ny"
value: "United States" or "New York"
parent_key: None for countries, "us" for states (cascading)
extra_data: {"code": "USA", "region": "north_america"}

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

Response

201CreatedSurveyService_SurveyResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Survey

GET

http://localhost:8001/api/v1/surveys/{survey_id}

Get a specific survey by ID.

Get Survey

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "survey_code": 0,
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "closed_at": "2024-01-15T09:30:00Z",
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false,
  "is_open": false,
  "schema": {
    "settings": {},
    "choices": [
      {}
    ],
    "questions": [
      {
        "type": "string",
        "name": "string",
        "label": "string",
        "label_translations": {},
        "required": false,
        "hint": "string",
        "hint_translations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraint_message_translations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "limit": {},
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "deidentify": false,
        "unique_id": false,
        "lookups": "string",
        "calendar_config": {},
        "calendar_rules": [
          {}
        ],
        "columns": [
          {}
        ]
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "project_status": "string",
  "project_has_production_activity": true,
  "project_production_activity_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_SurveyResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Survey

PUT

http://localhost:8001/api/v1/surveys/{survey_id}

Update survey metadata (not the schema).

Update Survey

curl -X PUT 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": true
}'

const body = `{
  "name": "string",
  "description": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": true
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": true
}'''

response = requests.put(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": true
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "survey_code": 0,
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "closed_at": "2024-01-15T09:30:00Z",
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false,
  "is_open": false,
  "schema": {
    "settings": {},
    "choices": [
      {}
    ],
    "questions": [
      {
        "type": "string",
        "name": "string",
        "label": "string",
        "label_translations": {},
        "required": false,
        "hint": "string",
        "hint_translations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraint_message_translations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "limit": {},
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "deidentify": false,
        "unique_id": false,
        "lookups": "string",
        "calendar_config": {},
        "calendar_rules": [
          {}
        ],
        "columns": [
          {}
        ]
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "project_status": "string",
  "project_has_production_activity": true,
  "project_production_activity_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

is_anonymousboolean | null

Show child attributes

Any of

boolean

null

allow_multiple_responsesboolean | null

Show child attributes

Any of

boolean

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledboolean | null

Show child attributes

Any of

boolean

null

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_SurveyResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Survey

DELETE

http://localhost:8001/api/v1/surveys/{survey_id}

Soft delete a survey (sets status to DELETED).

Delete Survey

curl -X DELETE 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Survey Status

PATCH

http://localhost:8001/api/v1/surveys/{survey_id}/status

Update survey status (DRAFT, PUBLISHED, ARCHIVED).

Update Survey Status

curl -X PATCH 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/status' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "status": "draft"
}'

const body = `{
  "status": "draft"
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/status', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "status": "draft"
}'''

response = requests.patch(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/status',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "status": "draft"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "survey_code": 0,
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "closed_at": "2024-01-15T09:30:00Z",
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false,
  "is_open": false,
  "schema": {
    "settings": {},
    "choices": [
      {}
    ],
    "questions": [
      {
        "type": "string",
        "name": "string",
        "label": "string",
        "label_translations": {},
        "required": false,
        "hint": "string",
        "hint_translations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraint_message_translations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "limit": {},
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "deidentify": false,
        "unique_id": false,
        "lookups": "string",
        "calendar_config": {},
        "calendar_rules": [
          {}
        ],
        "columns": [
          {}
        ]
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "project_status": "string",
  "project_has_production_activity": true,
  "project_production_activity_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

statusSurveyService_SurveyStatusdraftpublishedarchivedrequired

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_SurveyResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Duplicate Survey

POST

http://localhost:8001/api/v1/surveys/{survey_id}/duplicate

Duplicate an existing survey including schema, settings, and lookups.

Creates a new survey with copied data (schema, settings, choices, lookups)
Resets status to DRAFT for duplicated survey
Generates new survey_code and RID counter
Optionally copies form access rules if copy_access_settings=True
Does NOT copy version history (starts fresh)

Duplicate Survey

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/duplicate?copy_access_settings=false'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/duplicate?copy_access_settings=false', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/duplicate?copy_access_settings=false')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

new_namestring | nullquery

copy_access_settingsbooleanfalsequery

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Survey Schedule

PUT

http://localhost:8001/api/v1/surveys/{survey_id}/schedule

Update survey open/close schedule.

Update Survey Schedule

curl -X PUT 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/schedule' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": true
}'

const body = `{
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": true
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/schedule', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": true
}'''

response = requests.put(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/schedule',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": true
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "survey_code": 0,
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "closed_at": "2024-01-15T09:30:00Z",
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false,
  "is_open": false,
  "schema": {
    "settings": {},
    "choices": [
      {}
    ],
    "questions": [
      {
        "type": "string",
        "name": "string",
        "label": "string",
        "label_translations": {},
        "required": false,
        "hint": "string",
        "hint_translations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraint_message_translations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "limit": {},
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "deidentify": false,
        "unique_id": false,
        "lookups": "string",
        "calendar_config": {},
        "calendar_rules": [
          {}
        ],
        "columns": [
          {}
        ]
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "project_status": "string",
  "project_has_production_activity": true,
  "project_production_activity_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleantrue

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_SurveyResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Survey Schema

GET

http://localhost:8001/api/v1/surveys/{survey_id}/schema

Get the survey design schema (form builder data).

Enriched with media audio URLs/asset IDs (deep copy — the stored draft schema is never mutated) so the mobile fallback sync path (GET /surveys/{id}/schema) delivers human audio the same way published versions do.

Get Survey Schema

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/schema'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/schema', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/schema')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Survey Schema

PUT

http://localhost:8001/api/v1/surveys/{survey_id}/schema

Update the survey design schema (form builder data).

Update Survey Schema

curl -X PUT 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/schema' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/schema', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body: '{}',
});

const data = await response.text();

import requests

response = requests.put(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/schema',
    data='{}'.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

object

Parameters

survey_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get lookup data for auto-population

GET

http://localhost:8001/api/v1/surveys/{survey_id}/lookup-data

Returns lookup data for form auto-population. Used by form-service to cache lookup data.

Get lookup data for auto-population

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/lookup-data'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/lookup-data', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/lookup-data')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring | nullquery

Specific version ID (optional)

filter_user_idstring | nullquery

Filter lookup data for specific user's assigned triggers

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Import Xlsform

POST

http://localhost:8001/api/v1/surveys/import-xlsform

Import a survey from an XLSForm Excel file (.xlsx).

The XLSForm file should contain the following worksheets:

survey (required): Question definitions with columns: type, name, label, hint, required, etc.
choices (optional): Choice lists for select_one/select_multiple questions
settings (optional): Form metadata (form_title, form_id, version, etc.)
lookups (optional, custom): External lookup data for cascading selects

Reference: https://xlsform.org/en/

The imported survey will be created in DRAFT status with the parsed schema.

Import Xlsform

curl -X POST 'http://localhost:8001/api/v1/surveys/import-xlsform' \
  --form-string 'file=string' \
  --form-string 'name=string' \
  --form-string 'description=string' \
  --form-string 'project_id=550e8400-e29b-41d4-a716-446655440000' \
  --form-string 'workspace_id=550e8400-e29b-41d4-a716-446655440000' \
  --form-string 'is_anonymous=false' \
  --form-string 'allow_multiple_responses=false' \
  --form-string 'scheduling_enabled=false' \
  --form-string 'open_at=2024-01-15T09:30:00Z' \
  --form-string 'close_at=2024-01-15T09:30:00Z'

const form = new FormData();
form.append('file', 'string');
form.append('name', 'string');
form.append('description', 'string');
form.append('project_id', '550e8400-e29b-41d4-a716-446655440000');
form.append('workspace_id', '550e8400-e29b-41d4-a716-446655440000');
form.append('is_anonymous', 'false');
form.append('allow_multiple_responses', 'false');
form.append('scheduling_enabled', 'false');
form.append('open_at', '2024-01-15T09:30:00Z');
form.append('close_at', '2024-01-15T09:30:00Z');
const response = await fetch('http://localhost:8001/api/v1/surveys/import-xlsform', {
  method: 'POST',
  headers: {},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('file', (None, 'string')),
        ('name', (None, 'string')),
        ('description', (None, 'string')),
        ('project_id', (None, '550e8400-e29b-41d4-a716-446655440000')),
        ('workspace_id', (None, '550e8400-e29b-41d4-a716-446655440000')),
        ('is_anonymous', (None, 'false')),
        ('allow_multiple_responses', (None, 'false')),
        ('scheduling_enabled', (None, 'false')),
        ('open_at', (None, '2024-01-15T09:30:00Z')),
        ('close_at', (None, '2024-01-15T09:30:00Z')),
    ]
    response = requests.request('POST', 'http://localhost:8001/api/v1/surveys/import-xlsform', headers={}, files=files)
    print(response.text)

Request Body

{
  "file": "string",
  "name": "string",
  "description": "string",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "scheduling_enabled": false,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "survey_code": 0,
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "closed_at": "2024-01-15T09:30:00Z",
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false,
  "is_open": false,
  "schema": {
    "settings": {},
    "choices": [
      {}
    ],
    "questions": [
      {
        "type": "string",
        "name": "string",
        "label": "string",
        "label_translations": {},
        "required": false,
        "hint": "string",
        "hint_translations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraint_message_translations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "limit": {},
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "deidentify": false,
        "unique_id": false,
        "lookups": "string",
        "calendar_config": {},
        "calendar_rules": [
          {}
        ],
        "columns": [
          {}
        ]
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "project_status": "string",
  "project_has_production_activity": true,
  "project_production_activity_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filestringrequired

XLSForm Excel file (.xlsx)

namestringrequired

Survey name

descriptionstring | null

Survey description

Show child attributes

Any of

string

null

project_idstring<uuid>required

Project ID from workspace-service

workspace_idstring<uuid>required

Workspace ID for the project

is_anonymousbooleanfalse

Whether responses are anonymous

allow_multiple_responsesbooleanfalse

Allow multiple responses per user

scheduling_enabledbooleanfalse

Enable survey scheduling (auto open/close)

open_atstring | null

Scheduled open timestamp (ISO 8601)

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Scheduled close timestamp (ISO 8601)

Show child attributes

Any of

string<date-time>

null

Response

201CreatedSurveyService_SurveyResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Download a starter XLSForm template

GET

http://localhost:8001/api/v1/surveys/import-xlsform/download

Download a starter .xlsx XLSForm workbook that can be filled in and re-imported via POST /surveys/import-xlsform.

Download a starter XLSForm template

curl -X GET 'http://localhost:8001/api/v1/surveys/import-xlsform/download'

const response = await fetch('http://localhost:8001/api/v1/surveys/import-xlsform/download', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/import-xlsform/download')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Validate a single expression

POST

http://localhost:8001/api/v1/surveys/expressions/validate

Validate a skip logic, constraint, or calculation expression against available fields.

Validate a single expression

curl -X POST 'http://localhost:8001/api/v1/surveys/expressions/validate' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "expression": "string",
  "expression_type": "relevant",
  "available_fields": [
    "string"
  ]
}'

const body = `{
  "expression": "string",
  "expression_type": "relevant",
  "available_fields": [
    "string"
  ]
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/expressions/validate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "expression": "string",
  "expression_type": "relevant",
  "available_fields": [
    "string"
  ]
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/expressions/validate',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "expression": "string",
  "expression_type": "relevant",
  "available_fields": [
    "string"
  ]
}

{
  "is_valid": true,
  "expression": "string",
  "expression_type": "string",
  "errors": [
    {
      "field": "string",
      "message": "string",
      "code": "string",
      "context": {}
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request body for expression validation endpoint.

expressionstringrequired

The expression to validate (XPath format with ${field_name} references)

expression_typestringrelevant

Type of expression being validated

available_fieldsArray<string>

List of available question/field names for reference validation

Response

200OKSurveyService_ExpressionValidationResponse

Successful Response

Response fields application/json

Response from expression validation endpoint.

is_validbooleanrequired

expressionstringrequired

expression_typestringrequired

errorsArray<SurveyService_ExpressionValidationError>

Show child attributes

A single validation error for expression validation.

fieldstringrequired

messagestringrequired

codestringrequired

contextobject | null

Show child attributes

Any of

object

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

List Survey Media

GET

http://localhost:8001/api/v1/surveys/{survey_id}/media

List all media assets for a survey.

List Survey Media

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/media'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/media', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/media')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Upload Survey Media

POST

http://localhost:8001/api/v1/surveys/{survey_id}/media

Upload media assets (images, videos, audio) for survey questions.

The uploaded file must be a ZIP containing media files referenced in the survey schema's media_file field.

Media files are extracted and uploaded to the tenant's media library via the media-service.

Returns list of uploaded files and any missing files referenced in schema.

Upload Survey Media

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/media' \
  --form-string 'file=string'

const form = new FormData();
form.append('file', 'string');
const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/media', {
  method: 'POST',
  headers: {},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('file', (None, 'string')),
    ]
    response = requests.request('POST', 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/media', headers={}, files=files)
    print(response.text)

Request Body

{
  "file": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filestringrequired

ZIP file containing media assets

Parameters

survey_idstring<uuid>requiredpath

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Survey Service / Survey Versioning

Survey Versioning — Survey Service

List Versions

GET

http://localhost:8001/api/v1/surveys/{survey_id}/versions

List all versions of a survey.

List Versions

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions')
print(response.text)

[]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKArray<any>

Successful Response

Response fields application/json

Array<any>

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create New Version

POST

http://localhost:8001/api/v1/surveys/{survey_id}/versions

Create a new draft version of a survey.

Clones schema from previous published version (if exists)
Increments version number using semantic versioning (Major.Minor.Patch)
Creates in DRAFT status only
Sets is_immutable=False

Create New Version

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema": {
    "settings": {
      "form_title": "string",
      "form_id": "string",
      "version": "string",
      "defaultLanguage": "en",
      "languages": [
        "string"
      ],
      "availableLanguages": [
        "string"
      ],
      "instanceName": "string",
      "submissionUrl": "string"
    },
    "choices": [
      {
        "list_name": "string",
        "name": "string",
        "label": "string",
        "labelTranslations": {},
        "media_file": "string",
        "constraint": "string"
      }
    ],
    "questions": [
      {
        "type": "text",
        "name": "string",
        "label": "",
        "required": false,
        "hint": "string",
        "labelTranslations": {},
        "hintTranslations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraintMessageTranslations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "calendar_config": {
          "mode": "monthly",
          "months_back": 12,
          "start_from": "today",
          "allow_future": false
        },
        "calendar_rules": [
          {
            "id": "string",
            "trigger_question": "string",
            "target_column": "string",
            "value_source": "constant",
            "source_value": "string",
            "backfill_months": 1,
            "backfill_anchor": "current_month",
            "map_values": {},
            "xpath_expression": "string",
            "enabled": true,
            "conditions": [
              {}
            ],
            "months_scope": {}
          }
        ],
        "columns": [
          {
            "key": "string",
            "type": "select_one",
            "label": "",
            "label_translations": {},
            "choices": [
              {}
            ],
            "relevant": "string"
          }
        ],
        "limit": {
          "min": 0,
          "max": 0
        },
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "mediaAudio": "string",
        "mediaAudioSchema": {},
        "mediaAudioUrl": "string",
        "mediaAudioAssetId": "string",
        "mediaAudioUrlSchema": {},
        "mediaAudioAssetIdSchema": {},
        "deidentify": false,
        "unique_id": false,
        "lookups": "string"
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "version": "string",
  "increment_type": "patch"
}'

const body = `{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema": {
    "settings": {
      "form_title": "string",
      "form_id": "string",
      "version": "string",
      "defaultLanguage": "en",
      "languages": [
        "string"
      ],
      "availableLanguages": [
        "string"
      ],
      "instanceName": "string",
      "submissionUrl": "string"
    },
    "choices": [
      {
        "list_name": "string",
        "name": "string",
        "label": "string",
        "labelTranslations": {},
        "media_file": "string",
        "constraint": "string"
      }
    ],
    "questions": [
      {
        "type": "text",
        "name": "string",
        "label": "",
        "required": false,
        "hint": "string",
        "labelTranslations": {},
        "hintTranslations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraintMessageTranslations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "calendar_config": {
          "mode": "monthly",
          "months_back": 12,
          "start_from": "today",
          "allow_future": false
        },
        "calendar_rules": [
          {
            "id": "string",
            "trigger_question": "string",
            "target_column": "string",
            "value_source": "constant",
            "source_value": "string",
            "backfill_months": 1,
            "backfill_anchor": "current_month",
            "map_values": {},
            "xpath_expression": "string",
            "enabled": true,
            "conditions": [
              {}
            ],
            "months_scope": {}
          }
        ],
        "columns": [
          {
            "key": "string",
            "type": "select_one",
            "label": "",
            "label_translations": {},
            "choices": [
              {}
            ],
            "relevant": "string"
          }
        ],
        "limit": {
          "min": 0,
          "max": 0
        },
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "mediaAudio": "string",
        "mediaAudioSchema": {},
        "mediaAudioUrl": "string",
        "mediaAudioAssetId": "string",
        "mediaAudioUrlSchema": {},
        "mediaAudioAssetIdSchema": {},
        "deidentify": false,
        "unique_id": false,
        "lookups": "string"
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "version": "string",
  "increment_type": "patch"
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema": {
    "settings": {
      "form_title": "string",
      "form_id": "string",
      "version": "string",
      "defaultLanguage": "en",
      "languages": [
        "string"
      ],
      "availableLanguages": [
        "string"
      ],
      "instanceName": "string",
      "submissionUrl": "string"
    },
    "choices": [
      {
        "list_name": "string",
        "name": "string",
        "label": "string",
        "labelTranslations": {},
        "media_file": "string",
        "constraint": "string"
      }
    ],
    "questions": [
      {
        "type": "text",
        "name": "string",
        "label": "",
        "required": false,
        "hint": "string",
        "labelTranslations": {},
        "hintTranslations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraintMessageTranslations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "calendar_config": {
          "mode": "monthly",
          "months_back": 12,
          "start_from": "today",
          "allow_future": false
        },
        "calendar_rules": [
          {
            "id": "string",
            "trigger_question": "string",
            "target_column": "string",
            "value_source": "constant",
            "source_value": "string",
            "backfill_months": 1,
            "backfill_anchor": "current_month",
            "map_values": {},
            "xpath_expression": "string",
            "enabled": true,
            "conditions": [
              {}
            ],
            "months_scope": {}
          }
        ],
        "columns": [
          {
            "key": "string",
            "type": "select_one",
            "label": "",
            "label_translations": {},
            "choices": [
              {}
            ],
            "relevant": "string"
          }
        ],
        "limit": {
          "min": 0,
          "max": 0
        },
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "mediaAudio": "string",
        "mediaAudioSchema": {},
        "mediaAudioUrl": "string",
        "mediaAudioAssetId": "string",
        "mediaAudioUrlSchema": {},
        "mediaAudioAssetIdSchema": {},
        "deidentify": false,
        "unique_id": false,
        "lookups": "string"
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "version": "string",
  "increment_type": "patch"
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema": {
    "settings": {
      "form_title": "string",
      "form_id": "string",
      "version": "string",
      "defaultLanguage": "en",
      "languages": [
        "string"
      ],
      "availableLanguages": [
        "string"
      ],
      "instanceName": "string",
      "submissionUrl": "string"
    },
    "choices": [
      {
        "list_name": "string",
        "name": "string",
        "label": "string",
        "labelTranslations": {},
        "media_file": "string",
        "constraint": "string"
      }
    ],
    "questions": [
      {
        "type": "text",
        "name": "string",
        "label": "",
        "required": false,
        "hint": "string",
        "labelTranslations": {},
        "hintTranslations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraintMessageTranslations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "calendar_config": {
          "mode": "monthly",
          "months_back": 12,
          "start_from": "today",
          "allow_future": false
        },
        "calendar_rules": [
          {
            "id": "string",
            "trigger_question": "string",
            "target_column": "string",
            "value_source": "constant",
            "source_value": "string",
            "backfill_months": 1,
            "backfill_anchor": "current_month",
            "map_values": {},
            "xpath_expression": "string",
            "enabled": true,
            "conditions": [
              {}
            ],
            "months_scope": {}
          }
        ],
        "columns": [
          {
            "key": "string",
            "type": "select_one",
            "label": "",
            "label_translations": {},
            "choices": [
              {}
            ],
            "relevant": "string"
          }
        ],
        "limit": {
          "min": 0,
          "max": 0
        },
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "mediaAudio": "string",
        "mediaAudioSchema": {},
        "mediaAudioUrl": "string",
        "mediaAudioAssetId": "string",
        "mediaAudioUrlSchema": {},
        "mediaAudioAssetIdSchema": {},
        "deidentify": false,
        "unique_id": false,
        "lookups": "string"
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "version": "string",
  "increment_type": "patch"
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Any of

DTO for creating a new survey version

survey_idstring | null

Show child attributes

Any of

string<uuid>

null

schemaSurveyService_SurveySchema | null

Show child attributes

Any of

Complete XLSForm-compatible survey schema. Stored in JSONB column in survey_versions table. Includes support for custom lookups worksheet for cascading selects.

settingsSurveyService_SettingsSchemarequired

Survey-level settings (XLSForm settings sheet)

Show child attributes

form_titlestringrequired

form_idstring | null

Show child attributes

Any of

string

null

versionstring | null

Show child attributes

Any of

string

null

defaultLanguagestring | nullen

Show child attributes

Any of

string

null

languagesArray<string> | null

Show child attributes

Any of

Array<string>

null

availableLanguagesArray<string> | null

Show child attributes

Any of

Array<string>

null

instanceNamestring | null

Show child attributes

Any of

string

null

submissionUrlstring | null

Show child attributes

Any of

string

null

choicesArray<SurveyService_ChoiceSchema>

Show child attributes

Choice list item (XLSForm choices sheet)

list_namestringrequired

namestringrequired

labelstringrequired

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

media_filestring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionSchema>required

Show child attributes

XLSForm-compatible question schema. Supports all 22 question types with recursive nesting for groups/repeats.

Complete XLSForm-compatible question types (KoboToolbox standard). Reference: https://xlsform.org/en/#question-types

namestringrequired

labelstring

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

hintTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraintMessageTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | null

Show child attributes

Any of

string

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionSchema> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionSchema>

null

calendar_configSurveyService_CalendarConfigSchema | null

Show child attributes

Any of

Configuration for calendar_grid question type

modestringmonthly

months_backinteger[1, 120]12

start_fromstringtoday

allow_futurebooleanfalse

null

calendar_rulesArray<SurveyService_CalendarRuleSchema> | null

Auto-prefill rules for calendar columns

Show child attributes

Any of

Array<SurveyService_CalendarRuleSchema>

Show child attributes

Rule for auto-prefilling calendar column values

idstring | null

Unique rule ID

Show child attributes

Any of

string

null

trigger_questionstringrequired

Question name that triggers this rule

target_columnstringrequired

Calendar column key to fill

value_sourcestringconstant

Where to get the value: constant, lookup, or xpath expression

source_valuestring | null

Constant value to fill (for constant source)

Show child attributes

Any of

string

null

backfill_monthsinteger | null1

How many months to backfill from anchor

Show child attributes

Any of

integer[1, 120]

null

backfill_anchorstring | SurveyService_BackfillAnchorSchema | nullcurrent_month

Anchor for backfill: 'current_month', or anchor config object

Show child attributes

Any of

string

Anchor configuration for timeline-aware backfill

typestringrequired

Anchor type

questionstring | null

Question name (for from_answer_month type)

Show child attributes

Max depth reached

rule_idstring | null

Rule ID to anchor to (for before_rule/after_rule types)

Show child attributes

Max depth reached

null

map_valuesobject | null

Map trigger values to calendar values (e.g., {'yes': 'Y', 'no': 'N'})

Show child attributes

Any of

[key: string]string

null

xpath_expressionstring | null

XPath expression to calculate value (for xpath source)

Show child attributes

Any of

string

null

enabledbooleantrue

Whether rule is active

conditionsArray<object> | null

Conditions for when the rule applies (Visual Rule Builder)

Show child attributes

Any of

Array<object>

null

months_scopeobject | null

Months scope configuration for the rule

Show child attributes

Any of

object

null

columnsArray<SurveyService_CalendarColumnSchema> | null

Show child attributes

Any of

Array<SurveyService_CalendarColumnSchema>

Show child attributes

Column definition for calendar_grid question type

keystringrequired

typestringselect_one

labelstring

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

choicesArray<object> | null

Choices for select_one type - name must be exactly 1 character

Show child attributes

Any of

Array<object>

null

relevantstring | null

Show child attributes

Any of

string

null

limitSurveyService_LimitSchema | null

Show child attributes

Any of

Limit configuration for text/number fields. For text: min/max character count For integer/decimal: min/max value

mininteger | null

Show child attributes

Any of

integer

null

maxinteger | null

Show child attributes

Any of

integer

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

mediaAudiostring | null

Show child attributes

Any of

string

null

mediaAudioSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioUrlstring | null

Show child attributes

Any of

string

null

mediaAudioAssetIdstring | null

Show child attributes

Any of

string

null

mediaAudioUrlSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioAssetIdSchemaobject | null

Show child attributes

Any of

[key: string]string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

lookupsArray<SurveyService_LookupSchema>

Show child attributes

Lookup data item (custom lookups worksheet). Used for cascading selects and external data lookups.

Example:

lookup_name: "countries" or "states"
key: "us" or "ny"
value: "United States" or "New York"
parent_key: None for countries, "us" for states (cascading)
extra_data: {"code": "USA", "region": "north_america"}

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

versionstring | null

Show child attributes

Any of

string

null

increment_typestring | nullpatch

Show child attributes

Any of

string

null

Parameters

survey_idstring<uuid>requiredpath

Response

201Createdobject

Successful Response

Response fields application/json

object

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Version

GET

http://localhost:8001/api/v1/surveys/{survey_id}/versions/{version_id}

Get a specific version of a survey.

Get Version

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring<uuid>requiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Version Schema

PUT

http://localhost:8001/api/v1/surveys/{survey_id}/versions/{version_id}

Update schema for a draft version.

Only allowed for DRAFT versions
Version must be immutable=False

Accepts schema in two formats:

Direct format: { settings, choices, questions, ... }
Wrapped format: { schema: { settings, choices, questions, ... } }

Update Version Schema

curl -X PUT 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "schema": {}
}'

const body = `{
  "schema": {}
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "schema": {}
}'''

response = requests.put(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "schema": {}
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

DTO for updating a draft survey version (cannot update published).

Accepts schema in two formats:

Direct format: { settings, choices, questions, ... }
Wrapped format: { schema: { settings, choices, questions, ... } }

The 'schema' field (when present) may include additional metadata like 'title' and 'version' which are stripped during parsing.

schemaobject | null

Show child attributes

Any of

object

null

settingsany | null

Show child attributes

Any of

any

null

choicesany | null

Show child attributes

Any of

any

null

questionsany | null

Show child attributes

Any of

any

null

lookupsany | null

Show child attributes

Any of

any

null

lookup_dataany | null

Show child attributes

Any of

any

null

Parameters

survey_idstring<uuid>requiredpath

version_idstring<uuid>requiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Discard Version

DELETE

http://localhost:8001/api/v1/surveys/{survey_id}/versions/{version_id}

Discard a draft version.

Only allowed for DRAFT versions
Published versions cannot be deleted (for audit trail)

Discard Version

curl -X DELETE 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Clone Version To New Draft

POST

http://localhost:8001/api/v1/surveys/{survey_id}/versions/{version_id}/clone

Clone an existing version to a new draft.

Creates a new version with incremented number using semantic versioning
Copies schema from source version
New version is in DRAFT status

Clone Version To New Draft

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/clone?increment_type=patch'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/clone?increment_type=patch', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/clone?increment_type=patch')
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring<uuid>requiredpath

increment_typestring | nullpatchquery

major, minor, patch

Response

201Createdobject

Successful Response

Response fields application/json

object

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Latest Version

GET

http://localhost:8001/api/v1/surveys/{survey_id}/versions/latest

Get the latest version of a survey.

Returns the most recently created version (highest version number). Used by other services (form-service, data-service) to fetch current schema.

Get Latest Version

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/latest'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/latest', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/latest')
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Fetch the content-addressed schema artifact for a version

GET

http://localhost:8001/api/v1/surveys/{survey_id}/versions/{version_id}/schema-artifact

Returns the governing schema artifact for a survey version: canonical_schema is the exact string whose UTF-8 bytes hash to schema_sha256. Unlike the render endpoints this performs no media-audio enrichment, so the served bytes and the declared digest always agree. A client verifies by hashing canonical_schema and comparing to schema_sha256; it must not re-serialize a parsed copy.

Fetch the content-addressed schema artifact for a version

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/schema-artifact'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/schema-artifact', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/schema-artifact')
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring<uuid>requiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Export survey version as XLSForm

GET

http://localhost:8001/api/v1/surveys/{survey_id}/versions/{version_id}/export-xlsform

Download a survey version as an XLSForm .xlsx file with optional language selection.

Export survey version as XLSForm

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/export-xlsform'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/export-xlsform', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/export-xlsform')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring<uuid>requiredpath

survey_namestring | nullquery

Override filename prefix

languagesstring | nullquery

Comma-separated list of language codes to export (e.g., 'en,es,fr'). If not specified, exports all available languages from the schema.

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Survey Service / Survey Publishing

Survey Publishing — Survey Service

Publish Check

GET

http://localhost:8001/api/v1/surveys/{survey_id}/publish-check

Check whether publishing a new version of this survey is safe.

Returns warnings if the survey has active data collection in progress. This is a pre-publish check — it does NOT block publishing, only warns.

Publish Check

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/publish-check'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/publish-check', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/publish-check')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Publish Survey

POST

http://localhost:8001/api/v1/surveys/{survey_id}/publish

Publish a survey.

Optional version_id query param to publish a specific version (e.g. republish an old one).
When omitted, the latest version is used.
Validates schema using validation engine (first-time publishes only).
Marks version as immutable and sets published_at timestamp.
Updates survey status to PUBLISHED.

Publish Survey

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/publish'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/publish', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/publish')
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "survey_code": 0,
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "closed_at": "2024-01-15T09:30:00Z",
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false,
  "is_open": false,
  "schema": {
    "settings": {},
    "choices": [
      {}
    ],
    "questions": [
      {
        "type": "string",
        "name": "string",
        "label": "string",
        "label_translations": {},
        "required": false,
        "hint": "string",
        "hint_translations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraint_message_translations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "limit": {},
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "deidentify": false,
        "unique_id": false,
        "lookups": "string",
        "calendar_config": {},
        "calendar_rules": [
          {}
        ],
        "columns": [
          {}
        ]
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "project_status": "string",
  "project_has_production_activity": true,
  "project_production_activity_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring | nullquery

Response

200OKSurveyService_SurveyResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Unpublish Survey

POST

http://localhost:8001/api/v1/surveys/{survey_id}/unpublish

Unpublish a survey (set back to draft).

Only allows unpublishing if survey is published
Does NOT modify version (remains immutable for audit)
Sets survey status back to DRAFT

Unpublish Survey

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/unpublish'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/unpublish', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/unpublish')
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "survey_code": 0,
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "closed_at": "2024-01-15T09:30:00Z",
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false,
  "is_open": false,
  "schema": {
    "settings": {},
    "choices": [
      {}
    ],
    "questions": [
      {
        "type": "string",
        "name": "string",
        "label": "string",
        "label_translations": {},
        "required": false,
        "hint": "string",
        "hint_translations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraint_message_translations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "limit": {},
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "deidentify": false,
        "unique_id": false,
        "lookups": "string",
        "calendar_config": {},
        "calendar_rules": [
          {}
        ],
        "columns": [
          {}
        ]
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "project_status": "string",
  "project_has_production_activity": true,
  "project_production_activity_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_SurveyResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Archive Survey

POST

http://localhost:8001/api/v1/surveys/{survey_id}/archive

Archive a survey permanently.

Archived surveys cannot be unarchived or reactivated
Form filling is blocked for archived surveys
Data viewing and analytics remain functional
Duplication is still allowed (creates a new DRAFT survey)

Archive Survey

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/archive'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/archive', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/archive')
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "survey_code": 0,
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "closed_at": "2024-01-15T09:30:00Z",
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false,
  "is_open": false,
  "schema": {
    "settings": {},
    "choices": [
      {}
    ],
    "questions": [
      {
        "type": "string",
        "name": "string",
        "label": "string",
        "label_translations": {},
        "required": false,
        "hint": "string",
        "hint_translations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraint_message_translations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "limit": {},
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "deidentify": false,
        "unique_id": false,
        "lookups": "string",
        "calendar_config": {},
        "calendar_rules": [
          {}
        ],
        "columns": [
          {}
        ]
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "project_status": "string",
  "project_has_production_activity": true,
  "project_production_activity_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_SurveyResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Published Version

GET

http://localhost:8001/api/v1/surveys/{survey_id}/published

Get the currently published version of a survey.

Get Published Version

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/published'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/published', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/published')
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

List Published Versions

GET

http://localhost:8001/api/v1/surveys/{survey_id}/versions/published

List all published versions of a survey (for audit trail).

List Published Versions

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/published'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/published', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/published')
print(response.text)

[]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKArray<any>

Successful Response

Response fields application/json

Array<any>

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Archive Version

POST

http://localhost:8001/api/v1/surveys/{survey_id}/versions/{version_id}/archive

Archive a published version.

Only published versions can be archived
Archived versions remain immutable for audit trail

Archive Version

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/archive'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/archive', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/versions/550e8400-e29b-41d4-a716-446655440000/archive')
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring<uuid>requiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Survey Version

GET

http://localhost:8001/api/v1/surveys/{survey_id}/version/{version_id}

Get a specific version of a survey by ID.

Get Survey Version

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/version/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/version/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/version/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring<uuid>requiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Survey Service / Form Access

Form Access — Survey Service

List Form Access

GET

http://localhost:8001/api/v1/surveys/{survey_id}/access

List all users who have access to a specific survey form.

Requires survey:grant_access or survey:manage permission.

List Form Access

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access?skip=0&limit=20&include_revoked=false'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access?skip=0&limit=20&include_revoked=false', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access?skip=0&limit=20&include_revoked=false')
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "granted_by": "550e8400-e29b-41d4-a716-446655440000",
      "access_level": "string",
      "expires_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "revoked_at": "2024-01-15T09:30:00Z",
      "revoked_by": "550e8400-e29b-41d4-a716-446655440000",
      "revocation_reason": "string",
      "user_email": "string",
      "user_first_name": "string",
      "user_last_name": "string",
      "user_code": "string",
      "user_role": "string",
      "assigned_triggers": [
        {
          "trigger_question": "string",
          "trigger_value": "string"
        }
      ]
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

skipinteger>= 00query

limitinteger[1, 100]20query

searchstring | nullquery

Search by user name or email

include_revokedbooleanfalsequery

Include soft-deleted tombstone assignments

Response

200OKSurveyService_FormAccessListResponse

Successful Response

Response fields application/json

itemsArray<SurveyService_FormAccessWithUserResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

survey_idstring<uuid>required

user_idstring<uuid>required

granted_bystring<uuid>required

access_levelstringrequired

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

revoked_atstring | null

Show child attributes

Any of

string<date-time>

null

revoked_bystring | null

Show child attributes

Any of

string<uuid>

null

revocation_reasonstring | null

Show child attributes

Any of

string

null

user_emailstring | null

Show child attributes

Any of

string

null

user_first_namestring | null

Show child attributes

Any of

string

null

user_last_namestring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

user_rolestring | null

Show child attributes

Any of

string

null

assigned_triggersArray<SurveyService_LookupTriggerAssignment> | null

Show child attributes

Any of

Array<SurveyService_LookupTriggerAssignment>

Show child attributes

A single trigger value assignment for an enumerator.

trigger_questionstringrequired

Name of the trigger question, e.g., 's_state'

trigger_valuestringrequired

Value of the trigger, e.g., 'rajasthan'

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Grant Form Access

POST

http://localhost:8001/api/v1/surveys/{survey_id}/access

Grant a user access to fill a specific survey form.

Requires survey:grant_access or survey:manage permission.

Grant Form Access

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}'

const body = `{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "granted_by": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "string",
  "expires_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "revoked_at": "2024-01-15T09:30:00Z",
  "revoked_by": "550e8400-e29b-41d4-a716-446655440000",
  "revocation_reason": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

user_idstring<uuid>required

access_levelSurveyService_FormAccessLevelfillview_onlyapproverfill

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

assigned_triggersArray<SurveyService_LookupTriggerAssignment> | null

Show child attributes

Any of

Array<SurveyService_LookupTriggerAssignment>

Show child attributes

A single trigger value assignment for an enumerator.

trigger_questionstringrequired

Name of the trigger question, e.g., 's_state'

trigger_valuestringrequired

Value of the trigger, e.g., 'rajasthan'

null

Parameters

survey_idstring<uuid>requiredpath

Response

201CreatedSurveyService_FormAccessResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

survey_idstring<uuid>required

user_idstring<uuid>required

granted_bystring<uuid>required

access_levelstringrequired

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

revoked_atstring | null

Show child attributes

Any of

string<date-time>

null

revoked_bystring | null

Show child attributes

Any of

string<uuid>

null

revocation_reasonstring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Bulk Grant Form Access

POST

http://localhost:8001/api/v1/surveys/{survey_id}/access/bulk

Grant multiple users access to fill a specific survey form.

Requires survey:grant_access or survey:manage permission.

Bulk Grant Form Access

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/bulk' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "user_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}'

const body = `{
  "user_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/bulk', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "user_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/bulk',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "user_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

user_idsArray<string>required

access_levelSurveyService_FormAccessLevelfillview_onlyapproverfill

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

assigned_triggersArray<SurveyService_LookupTriggerAssignment> | null

Show child attributes

Any of

Array<SurveyService_LookupTriggerAssignment>

Show child attributes

A single trigger value assignment for an enumerator.

trigger_questionstringrequired

Name of the trigger question, e.g., 's_state'

trigger_valuestringrequired

Value of the trigger, e.g., 'rajasthan'

null

Parameters

survey_idstring<uuid>requiredpath

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

List User Form Access

GET

http://localhost:8001/api/v1/surveys/users/{user_id}/access

List all surveys a specific user currently has access to within the authenticated tenant.

This is the admin-facing counterpart to /surveys/access/my: instead of resolving the requesting user, it resolves an arbitrary tenant member.

tenant_id is always derived from the authenticated request; it is never accepted from the client, so cross-tenant assignments are never exposed.
The target user must be a member of the current tenant (same check used by grant_form_access). A non-member is rejected with 403 before any assignment data is read.

Requires survey:manage_access, survey:grant_access, or survey:manage.

List User Form Access

curl -X GET 'http://localhost:8001/api/v1/surveys/users/550e8400-e29b-41d4-a716-446655440000/access?skip=0&limit=20'

const response = await fetch('http://localhost:8001/api/v1/surveys/users/550e8400-e29b-41d4-a716-446655440000/access?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/users/550e8400-e29b-41d4-a716-446655440000/access?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "status": "string",
      "survey_code": 0,
      "version": "string",
      "access_level": "string",
      "can_fill": true,
      "can_view": true,
      "can_approve": false,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

user_idstring<uuid>requiredpath

skipinteger>= 00query

limitinteger[1, 100]20query

Response

200OKSurveyService_SurveyAccessListResponse

Successful Response

Response fields application/json

itemsArray<SurveyService_SurveyWithAccessResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

statusstringrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

versionstring | null

Show child attributes

Any of

string

null

access_levelstringrequired

can_fillbooleanrequired

can_viewbooleanrequired

can_approvebooleanfalse

created_atstring<date-time>required

updated_atstring | null

Show child attributes

Any of

string<date-time>

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Revoke Form Access

DELETE

http://localhost:8001/api/v1/surveys/{survey_id}/access/{target_user_id}

Revoke a user's access to a specific survey form as an auditable soft-delete tombstone (R17).

Requires survey:grant_access or survey:manage permission.

Revoke Form Access

curl -X DELETE 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "reason": "string"
}'

const body = `{
  "reason": "string"
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "reason": "string"
}'''

response = requests.delete(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "reason": "string"
}

{
  "message": "string",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "revoked_at": "2024-01-15T09:30:00Z",
  "revoked_by": "550e8400-e29b-41d4-a716-446655440000",
  "revocation_reason": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Any of

reasonstring | null

Auditable reason for revocation

Show child attributes

Any of

string

null

Parameters

survey_idstring<uuid>requiredpath

target_user_idstring<uuid>requiredpath

Response

200OKSurveyService_FormAccessRevokeResponse

Successful Response

Response fields application/json

messagestringrequired

user_idstring<uuid>required

survey_idstring<uuid>required

grant_idstring<uuid>required

revoked_atstring<date-time>required

revoked_bystring<uuid>required

revocation_reasonstring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Form Access

PATCH

http://localhost:8001/api/v1/surveys/{survey_id}/access/{target_user_id}

Update a user's access level or expiry for a specific survey form.

Requires survey:grant_access or survey:manage permission.

Update Form Access

curl -X PATCH 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}'

const body = `{
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}'''

response = requests.patch(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "granted_by": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "string",
  "expires_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "revoked_at": "2024-01-15T09:30:00Z",
  "revoked_by": "550e8400-e29b-41d4-a716-446655440000",
  "revocation_reason": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

access_levelSurveyService_FormAccessLevel | null

Show child attributes

Any of

SurveyService_FormAccessLevelfillview_onlyapprover

null

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

assigned_triggersArray<SurveyService_LookupTriggerAssignment> | null

Show child attributes

Any of

Array<SurveyService_LookupTriggerAssignment>

Show child attributes

A single trigger value assignment for an enumerator.

trigger_questionstringrequired

Name of the trigger question, e.g., 's_state'

trigger_valuestringrequired

Value of the trigger, e.g., 'rajasthan'

null

Parameters

survey_idstring<uuid>requiredpath

target_user_idstring<uuid>requiredpath

Response

200OKSurveyService_FormAccessResponse

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

survey_idstring<uuid>required

user_idstring<uuid>required

granted_bystring<uuid>required

access_levelstringrequired

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

revoked_atstring | null

Show child attributes

Any of

string<date-time>

null

revoked_bystring | null

Show child attributes

Any of

string<uuid>

null

revocation_reasonstring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Check Form Access

GET

http://localhost:8001/api/v1/surveys/{survey_id}/access/check

Check if the current user has access to a specific survey form.

This endpoint is public and doesn't require special permissions.

Check Form Access

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/check'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/check', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/check')
print(response.text)

{
  "has_access": true,
  "access_level": "string",
  "can_fill": false,
  "can_view": false,
  "can_approve": false,
  "expires_at": "2024-01-15T09:30:00Z",
  "is_open": true,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_blocked_reason": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_FormAccessCheckResponse

Successful Response

Response fields application/json

has_accessbooleanrequired

access_levelstring | null

Show child attributes

Any of

string

null

can_fillbooleanfalse

can_viewbooleanfalse

can_approvebooleanfalse

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

is_openbooleantrue

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_blocked_reasonstring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Check Historical Form Access

GET

http://localhost:8001/api/v1/surveys/{survey_id}/access/historical

Check if a user was authorized to collect/fill a survey at a specific historical point in time (R17 & R22).

Used by data-service / sync-service to validate that offline responses collected prior to revocation are eligible for governed reconciliation.

Check Historical Form Access

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/historical?user_id=550e8400-e29b-41d4-a716-446655440000&at_time=2024-01-15T09%3A30%3A00Z'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/historical?user_id=550e8400-e29b-41d4-a716-446655440000&at_time=2024-01-15T09%3A30%3A00Z', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/access/historical?user_id=550e8400-e29b-41d4-a716-446655440000&at_time=2024-01-15T09%3A30%3A00Z')
print(response.text)

{
  "has_access": true,
  "grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "revoked_at": "2024-01-15T09:30:00Z",
  "revocation_reason": "string",
  "is_revoked": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

user_idstring<uuid>requiredquery

User ID to check historical authorization for

at_timestring<date-time>requiredquery

ISO datetime at which access must have been valid

Response

200OKSurveyService_HistoricalAccessCheckResponse

Successful Response

Response fields application/json

has_accessbooleanrequired

grant_idstring | null

Show child attributes

Any of

string<uuid>

null

access_levelstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string<date-time>

null

revoked_atstring | null

Show child attributes

Any of

string<date-time>

null

revocation_reasonstring | null

Show child attributes

Any of

string

null

is_revokedbooleanfalse

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get My Accessible Surveys

GET

http://localhost:8001/api/v1/surveys/access/my

Get all surveys that the current user has access to.

When admin_access=true: Returns ALL published surveys in the tenant. The caller (mobile app) determines admin status from per-tenant role data received during login, and passes this flag accordingly.
When admin_access=false (default): Returns ONLY surveys explicitly assigned via form_access that are PUBLISHED, in an ACTIVE project, and carry the write-to-fill capability (can_fill). Read-only/approve-only grants and unpublished surveys are never offered for collection.

Per-tenant admin status CANNOT be determined from JWT permissions alone, because multi-tenant JWTs carry the PRIMARY tenant's permissions, which may differ from the user's role in the X-Tenant-ID tenant.

Get My Accessible Surveys

curl -X GET 'http://localhost:8001/api/v1/surveys/access/my?skip=0&limit=20&admin_access=false'

const response = await fetch('http://localhost:8001/api/v1/surveys/access/my?skip=0&limit=20&admin_access=false', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/access/my?skip=0&limit=20&admin_access=false')
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "status": "string",
      "survey_code": 0,
      "version": "string",
      "access_level": "string",
      "can_fill": true,
      "can_view": true,
      "can_approve": false,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

admin_accessbooleanfalsequery

If true, return ALL published surveys (for admin users). The caller must determine admin status from per-tenant role data.

Response

200OKSurveyService_SurveyAccessListResponse

Successful Response

Response fields application/json

itemsArray<SurveyService_SurveyWithAccessResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

statusstringrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

versionstring | null

Show child attributes

Any of

string

null

access_levelstringrequired

can_fillbooleanrequired

can_viewbooleanrequired

can_approvebooleanfalse

created_atstring<date-time>required

updated_atstring | null

Show child attributes

Any of

string<date-time>

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Enumerators For Supervisor

GET

http://localhost:8001/api/v1/surveys/access/enumerators

Get all enumerator user IDs that were granted access by the current Field Supervisor.

This is used by data-service to filter responses that Field Supervisors can see.

Get Enumerators For Supervisor

curl -X GET 'http://localhost:8001/api/v1/surveys/access/enumerators'

const response = await fetch('http://localhost:8001/api/v1/surveys/access/enumerators', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/access/enumerators')
print(response.text)

200

{
  "enumerator_ids": [
    "string"
  ]
}

Response

200OKSurveyService_EnumeratorListResponse

Successful Response

Response fields application/json

enumerator_idsArray<string>required

Survey Service / Project Lifecycle

Project Lifecycle — Survey Service

Relay Production Activity

POST

http://localhost:8001/api/v1/surveys/{survey_id}/production-activity

Mark that production collection has begun for a survey's project (internal).

Fail-closed: if the project cannot begin production activity (DRAFT or closed) or workspace-service is unreachable, this returns the workspace error and the CALLER MUST NOT proceed with the collection event.

Relay Production Activity

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/production-activity'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/production-activity', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/production-activity')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Issue Grant

POST

http://localhost:8001/api/v1/surveys/{survey_id}/collection-grants

Issue a durable collection grant (internal, service-auth only).

Called by sync-service (device_download on download acknowledgement) and form-service (interview_reservation at production interview creation). Grants are issued ONLY while the governing project is ACTIVE, and issuing one marks the project's monotonic production-activity invariant. The endpoint is idempotent — an existing identical binding is returned as-is, so re-acknowledgements after closure still resolve their original grant.

Issue Grant

curl -X POST 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/collection-grants' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "kind": "string",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema_hash": "string"
}'

const body = `{
  "kind": "string",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema_hash": "string"
}`;

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/collection-grants', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "kind": "string",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema_hash": "string"
}'''

response = requests.post(
    'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/collection-grants',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "kind": "string",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema_hash": "string"
}

{
  "id": "string",
  "kind": "string",
  "survey_id": "string",
  "survey_version_id": "string",
  "user_id": "string",
  "device_id": "string",
  "interview_id": "string",
  "project_status_at_issue": "string",
  "granted_at": "string",
  "project_bound": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

kindstringrequired

device_download | interview_reservation

user_idstring<uuid>required

survey_version_idstring<uuid>required

device_idstring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string<uuid>

null

schema_hashstring | null

Show child attributes

Any of

string

null

Parameters

survey_idstring<uuid>requiredpath

Response

200OKSurveyService_CollectionGrantResponse

Successful Response

Response fields application/json

idstringrequired

kindstringrequired

survey_idstringrequired

survey_version_idstringrequired

user_idstringrequired

device_idstring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

project_status_at_issuestringrequired

granted_atstring | null

Show child attributes

Any of

string

null

project_boundbooleantrue

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Validate Grant

GET

http://localhost:8001/api/v1/surveys/{survey_id}/collection-grants/validate

Authoritatively validate a submission's collection provenance (internal).

Called by data-service (response submission/edit) and media-service (media upload) when a project is no longer ACTIVE. Returns valid=true only when a matching grant was issued while the project was ACTIVE. Forged client-supplied identifiers never match (grants are server-created rows).

Validate Grant

curl -X GET 'http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/collection-grants/validate?user_id=550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/collection-grants/validate?user_id=550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/550e8400-e29b-41d4-a716-446655440000/collection-grants/validate?user_id=550e8400-e29b-41d4-a716-446655440000')
print(response.text)

{
  "valid": true,
  "project_bound": true,
  "grant_id": "string",
  "kind": "string",
  "survey_version_id": "string",
  "granted_at": "string",
  "project_status_at_issue": "string",
  "late_arrival_flagged": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

user_idstring<uuid>requiredquery

survey_version_idstring | nullquery

device_idstring | nullquery

interview_idstring | nullquery

Response

200OKSurveyService_ValidateCollectionGrantResponse

Successful Response

Response fields application/json

validbooleanrequired

project_boundbooleanrequired

grant_idstring | null

Show child attributes

Any of

string

null

kindstring | null

Show child attributes

Any of

string

null

survey_version_idstring | null

Show child attributes

Any of

string

null

granted_atstring | null

Show child attributes

Any of

string

null

project_status_at_issuestring | null

Show child attributes

Any of

string

null

late_arrival_flaggedbooleanfalse

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Mark Late Arrival

POST

http://localhost:8001/api/v1/surveys/collection-grants/{grant_id}/late-arrival

Flag a grant whose data landed after project closure (internal).

Called by data-service when it accepts a response for a non-ACTIVE project via a valid grant. The flag surfaces in supervisor review as a late-arrival warning — collection stays preserved, but is auditable.

Mark Late Arrival

curl -X POST 'http://localhost:8001/api/v1/surveys/collection-grants/550e8400-e29b-41d4-a716-446655440000/late-arrival'

const response = await fetch('http://localhost:8001/api/v1/surveys/collection-grants/550e8400-e29b-41d4-a716-446655440000/late-arrival', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/surveys/collection-grants/550e8400-e29b-41d4-a716-446655440000/late-arrival')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

grant_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Survey Service / Survey Name Lookup

Survey Name Lookup — Survey Service

Get Survey Name

GET

http://localhost:8001/api/v1/surveys/internal/name/{survey_id}

Return the display name for an internal survey_id (service-auth only).

Get Survey Name

curl -X GET 'http://localhost:8001/api/v1/surveys/internal/name/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8001/api/v1/surveys/internal/name/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/surveys/internal/name/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Survey Service / Template Categories

Template Categories — Survey Service

List Template Categories

GET

http://localhost:8001/api/v1/template-categories

List all template categories for the tenant.

List Template Categories

curl -X GET 'http://localhost:8001/api/v1/template-categories?skip=0&limit=20'

const response = await fetch('http://localhost:8001/api/v1/template-categories?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/template-categories?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "name": "string",
      "description": "string",
      "icon_name": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "skip": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

searchstring | nullquery

Search categories by name or description

Response

200OKSurveyService_TemplateCategoryListResponse

Successful Response

Response fields application/json

itemsArray<SurveyService_TemplateCategoryResponse>required

Show child attributes

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

totalintegerrequired

limitintegerrequired

skipintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Template Category

POST

http://localhost:8001/api/v1/template-categories

Create a new template category.

Create Template Category

curl -X POST 'http://localhost:8001/api/v1/template-categories' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "icon_name": "string"
}'

const body = `{
  "name": "string",
  "description": "string",
  "icon_name": "string"
}`;

const response = await fetch('http://localhost:8001/api/v1/template-categories', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "icon_name": "string"
}'''

response = requests.post(
    'http://localhost:8001/api/v1/template-categories',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "icon_name": "string"
}

{
  "id": "string",
  "tenant_id": "string",
  "name": "string",
  "description": "string",
  "icon_name": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

Response

201CreatedSurveyService_TemplateCategoryResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Template Category

GET

http://localhost:8001/api/v1/template-categories/{category_id}

Get a specific template category by ID.

Get Template Category

curl -X GET 'http://localhost:8001/api/v1/template-categories/string'

const response = await fetch('http://localhost:8001/api/v1/template-categories/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/template-categories/string')
print(response.text)

{
  "id": "string",
  "tenant_id": "string",
  "name": "string",
  "description": "string",
  "icon_name": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

category_idstringrequiredpath

Response

200OKSurveyService_TemplateCategoryResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Template Category

PUT

http://localhost:8001/api/v1/template-categories/{category_id}

Update a template category.

Update Template Category

curl -X PUT 'http://localhost:8001/api/v1/template-categories/string' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "icon_name": "string"
}'

const body = `{
  "name": "string",
  "description": "string",
  "icon_name": "string"
}`;

const response = await fetch('http://localhost:8001/api/v1/template-categories/string', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "icon_name": "string"
}'''

response = requests.put(
    'http://localhost:8001/api/v1/template-categories/string',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "icon_name": "string"
}

{
  "id": "string",
  "tenant_id": "string",
  "name": "string",
  "description": "string",
  "icon_name": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

Parameters

category_idstringrequiredpath

Response

200OKSurveyService_TemplateCategoryResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Template Category

DELETE

http://localhost:8001/api/v1/template-categories/{category_id}

Delete a template category.

Delete Template Category

curl -X DELETE 'http://localhost:8001/api/v1/template-categories/string'

const response = await fetch('http://localhost:8001/api/v1/template-categories/string', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8001/api/v1/template-categories/string')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

category_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Survey Service / Templates

Templates — Survey Service

List Templates

GET

http://localhost:8001/api/v1/templates

List all survey templates accessible for the tenant.

List Templates

curl -X GET 'http://localhost:8001/api/v1/templates?skip=0&limit=20'

const response = await fetch('http://localhost:8001/api/v1/templates?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/templates?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "category_id": "string",
      "name": "string",
      "description": "string",
      "schema": {},
      "is_public": true,
      "created_by": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "category": {
        "id": "string",
        "tenant_id": "string",
        "name": "string",
        "description": "string",
        "icon_name": "string",
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    }
  ],
  "total": 0,
  "limit": 0,
  "skip": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

category_idstring | nullquery

Filter templates by category

searchstring | nullquery

Search templates by name or description

Response

200OKSurveyService_SurveyTemplateListResponse

Successful Response

Response fields application/json

itemsArray<SurveyService_SurveyTemplateResponse>required

Show child attributes

idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

category_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanrequired

created_bystringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_TemplateCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

null

totalintegerrequired

limitintegerrequired

skipintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Template

POST

http://localhost:8001/api/v1/templates

Create a new survey template.

Create Template

curl -X POST 'http://localhost:8001/api/v1/templates' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "schema": {},
  "is_public": false,
  "category_id": "string",
  "tenant_id": "string"
}'

const body = `{
  "name": "string",
  "description": "string",
  "schema": {},
  "is_public": false,
  "category_id": "string",
  "tenant_id": "string"
}`;

const response = await fetch('http://localhost:8001/api/v1/templates', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "schema": {},
  "is_public": false,
  "category_id": "string",
  "tenant_id": "string"
}'''

response = requests.post(
    'http://localhost:8001/api/v1/templates',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "schema": {},
  "is_public": false,
  "category_id": "string",
  "tenant_id": "string"
}

{
  "id": "string",
  "tenant_id": "string",
  "category_id": "string",
  "name": "string",
  "description": "string",
  "schema": {},
  "is_public": true,
  "created_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "icon_name": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanfalse

category_idstringrequired

ID of the template category

tenant_idstring | null

Tenant ID (null for global templates)

Show child attributes

Any of

string

null

Response

201CreatedSurveyService_SurveyTemplateResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

category_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanrequired

created_bystringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_TemplateCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

List Templates Grouped

GET

http://localhost:8001/api/v1/templates/by-category

List all survey templates grouped by category.

List Templates Grouped

curl -X GET 'http://localhost:8001/api/v1/templates/by-category'

const response = await fetch('http://localhost:8001/api/v1/templates/by-category', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/templates/by-category')
print(response.text)

200

[
  {
    "category": {
      "id": "string",
      "tenant_id": "string",
      "name": "string",
      "description": "string",
      "icon_name": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    },
    "templates": [
      {
        "id": "string",
        "tenant_id": "string",
        "category_id": "string",
        "name": "string",
        "description": "string",
        "schema": {},
        "is_public": true,
        "created_by": "string",
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z",
        "category": {
          "id": "string",
          "tenant_id": "string",
          "name": "string",
          "description": "string",
          "icon_name": "string",
          "created_at": "2024-01-15T09:30:00Z",
          "updated_at": "2024-01-15T09:30:00Z"
        }
      }
    ],
    "template_count": 0
  }
]

Response

200OKArray<SurveyService_TemplatesByCategoryResponse>

Successful Response

Response fields application/json

Array<SurveyService_TemplatesByCategoryResponse>

Show child attributes

categorySurveyService_TemplateCategoryResponserequired

Show child attributes

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

templatesArray<SurveyService_SurveyTemplateResponse>required

Show child attributes

idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

category_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanrequired

created_bystringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_TemplateCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

null

template_countintegerrequired

Get Template

GET

http://localhost:8001/api/v1/templates/{template_id}

Get a specific survey template by ID.

Get Template

curl -X GET 'http://localhost:8001/api/v1/templates/string'

const response = await fetch('http://localhost:8001/api/v1/templates/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/templates/string')
print(response.text)

{
  "id": "string",
  "tenant_id": "string",
  "category_id": "string",
  "name": "string",
  "description": "string",
  "schema": {},
  "is_public": true,
  "created_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "icon_name": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

template_idstringrequiredpath

Response

200OKSurveyService_SurveyTemplateDetailResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

category_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanrequired

created_bystringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_TemplateCategoryResponserequired

Show child attributes

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Template

PUT

http://localhost:8001/api/v1/templates/{template_id}

Update a survey template.

Update Template

curl -X PUT 'http://localhost:8001/api/v1/templates/string' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "schema": {},
  "category_id": "string",
  "is_public": true
}'

const body = `{
  "name": "string",
  "description": "string",
  "schema": {},
  "category_id": "string",
  "is_public": true
}`;

const response = await fetch('http://localhost:8001/api/v1/templates/string', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "schema": {},
  "category_id": "string",
  "is_public": true
}'''

response = requests.put(
    'http://localhost:8001/api/v1/templates/string',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "schema": {},
  "category_id": "string",
  "is_public": true
}

{
  "id": "string",
  "tenant_id": "string",
  "category_id": "string",
  "name": "string",
  "description": "string",
  "schema": {},
  "is_public": true,
  "created_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "icon_name": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

category_idstring | null

Show child attributes

Any of

string

null

is_publicboolean | null

Show child attributes

Any of

boolean

null

Parameters

template_idstringrequiredpath

Response

200OKSurveyService_SurveyTemplateResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

category_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanrequired

created_bystringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_TemplateCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

null

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Template

DELETE

http://localhost:8001/api/v1/templates/{template_id}

Delete a survey template.

Delete Template

curl -X DELETE 'http://localhost:8001/api/v1/templates/string'

const response = await fetch('http://localhost:8001/api/v1/templates/string', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8001/api/v1/templates/string')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

template_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Import Template From Xlsform

POST

http://localhost:8001/api/v1/templates/import-xlsform

Import a survey template from an XLSForm Excel file (.xlsx).

The XLSForm file should contain the following worksheets:

survey (required): Question definitions with columns: type, name, label, hint, required, etc.
choices (optional): Choice lists for select_one/select_multiple questions
settings (optional): Form metadata (form_title, form_id, version, etc.)

Reference: https://xlsform.org/en/

Parses the uploaded file into a survey schema and persists it as a reusable template in the given category. The schema can later be used to create surveys via the create-from-template flow.

Import Template From Xlsform

curl -X POST 'http://localhost:8001/api/v1/templates/import-xlsform' \
  --form-string 'file=string' \
  --form-string 'name=string' \
  --form-string 'category_id=string' \
  --form-string 'description=string' \
  --form-string 'is_public=false'

const form = new FormData();
form.append('file', 'string');
form.append('name', 'string');
form.append('category_id', 'string');
form.append('description', 'string');
form.append('is_public', 'false');
const response = await fetch('http://localhost:8001/api/v1/templates/import-xlsform', {
  method: 'POST',
  headers: {},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('file', (None, 'string')),
        ('name', (None, 'string')),
        ('category_id', (None, 'string')),
        ('description', (None, 'string')),
        ('is_public', (None, 'false')),
    ]
    response = requests.request('POST', 'http://localhost:8001/api/v1/templates/import-xlsform', headers={}, files=files)
    print(response.text)

Request Body

{
  "file": "string",
  "name": "string",
  "category_id": "string",
  "description": "string",
  "is_public": false
}

{
  "id": "string",
  "tenant_id": "string",
  "category_id": "string",
  "name": "string",
  "description": "string",
  "schema": {},
  "is_public": true,
  "created_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "icon_name": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "import_warnings": [
    {}
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filestringrequired

XLSForm Excel file (.xlsx)

namestringrequired

Template name

category_idstringrequired

Template category ID

descriptionstring | null

Template description

Show child attributes

Any of

string

null

is_publicbooleanfalse

Whether the template is public

Response

201CreatedSurveyService_TemplateImportResponse

Successful Response

Response fields application/json

idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

category_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanrequired

created_bystringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_TemplateCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

null

import_warningsArray<object>

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Download a starter XLSForm template

GET

http://localhost:8001/api/v1/templates/import-xlsform/download

Download a starter .xlsx XLSForm workbook that can be filled in and re-imported via POST /templates/import-xlsform.

Download a starter XLSForm template

curl -X GET 'http://localhost:8001/api/v1/templates/import-xlsform/download'

const response = await fetch('http://localhost:8001/api/v1/templates/import-xlsform/download', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/templates/import-xlsform/download')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Create Survey From Template

POST

http://localhost:8001/api/v1/templates/create-survey

Create a new survey using a template's schema.

Create Survey From Template

curl -X POST 'http://localhost:8001/api/v1/templates/create-survey' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "template_id": "string",
  "name": "string",
  "description": "string",
  "workspace_id": "string",
  "project_id": "string",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "scheduling_enabled": false,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z"
}'

const body = `{
  "template_id": "string",
  "name": "string",
  "description": "string",
  "workspace_id": "string",
  "project_id": "string",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "scheduling_enabled": false,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z"
}`;

const response = await fetch('http://localhost:8001/api/v1/templates/create-survey', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "template_id": "string",
  "name": "string",
  "description": "string",
  "workspace_id": "string",
  "project_id": "string",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "scheduling_enabled": false,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z"
}'''

response = requests.post(
    'http://localhost:8001/api/v1/templates/create-survey',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "template_id": "string",
  "name": "string",
  "description": "string",
  "workspace_id": "string",
  "project_id": "string",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "scheduling_enabled": false,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z"
}

{
  "survey_id": "string",
  "name": "string",
  "template_id": "string",
  "created_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

template_idstringrequired

Template ID to create survey from

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

workspace_idstringrequired

Workspace ID for the new survey

project_idstringrequired

Project ID for the new survey

is_anonymousbooleanfalse

allow_multiple_responsesbooleanfalse

scheduling_enabledbooleanfalse

open_atstring | null

Scheduled open timestamp

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Scheduled close timestamp

Show child attributes

Any of

string<date-time>

null

Response

201CreatedSurveyService_CreateSurveyFromTemplateResponse

Successful Response

Response fields application/json

survey_idstringrequired

namestringrequired

template_idstringrequired

created_atstring<date-time>required

422Unprocessable EntitySurveyService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Seed Default Templates

POST

http://localhost:8001/api/v1/templates/seed

Seed default template categories and templates if none exist.

This endpoint is idempotent - safe to call multiple times. Default categories: Census, Health, Education, Agriculture Default templates: Standard Census Form, Community Health Assessment

Seed Default Templates

curl -X POST 'http://localhost:8001/api/v1/templates/seed'

const response = await fetch('http://localhost:8001/api/v1/templates/seed', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/templates/seed')
print(response.text)

200

{}

Response

200OKobject

Successful Response

Response fields application/json

object

Survey Service / Health

Health — Survey Service

Check Survey Schedules

POST

http://localhost:8001/api/v1/surveys/check-schedules

Manually trigger survey schedule check for the tenant.

Check Survey Schedules

curl -X POST 'http://localhost:8001/api/v1/surveys/check-schedules'

const response = await fetch('http://localhost:8001/api/v1/surveys/check-schedules', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/surveys/check-schedules')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Data Service

Response storage, editing, approvals, exports, attachments, bulk operations, sampling

Data Service / Bulk Responses

Bulk Responses — Data Service

Ingest Bulk Responses

POST

http://localhost:8002/api/v1/responses/bulk

Ingest multiple survey responses in bulk.

Idempotent: Same idempotency_key returns same response
Max batch size: 100 responses per request
Partial success: Failed items don't block successful ones
Transactional: Each response created in own transaction

Ingest Bulk Responses

curl -X POST 'http://localhost:8002/api/v1/responses/bulk' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "responses": [
    {
      "idempotency_key": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "version_id": "550e8400-e29b-41d4-a716-446655440000",
      "respondent_id": "string",
      "answers": {},
      "metadata": {},
      "submitted_at": "2024-01-15T09:30:00Z"
    }
  ]
}'

const body = `{
  "responses": [
    {
      "idempotency_key": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "version_id": "550e8400-e29b-41d4-a716-446655440000",
      "respondent_id": "string",
      "answers": {},
      "metadata": {},
      "submitted_at": "2024-01-15T09:30:00Z"
    }
  ]
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/bulk', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "responses": [
    {
      "idempotency_key": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "version_id": "550e8400-e29b-41d4-a716-446655440000",
      "respondent_id": "string",
      "answers": {},
      "metadata": {},
      "submitted_at": "2024-01-15T09:30:00Z"
    }
  ]
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/bulk',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "responses": [
    {
      "idempotency_key": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "version_id": "550e8400-e29b-41d4-a716-446655440000",
      "respondent_id": "string",
      "answers": {},
      "metadata": {},
      "submitted_at": "2024-01-15T09:30:00Z"
    }
  ]
}

{
  "total": 0,
  "successful": 0,
  "failed": 0,
  "results": [
    {
      "idempotency_key": "string",
      "response_id": "string",
      "status": "string",
      "error": "string",
      "submitted_at": "string"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

responsesArray<DataService_BulkResponseItemDTO>required

Show child attributes

idempotency_keystringrequired

Unique key for idempotency

survey_idstring<uuid>required

Survey ID

version_idstring | null

Survey version ID

Show child attributes

Any of

string<uuid>

null

respondent_idstring | null

Show child attributes

Any of

string

null

answersobjectrequired

Question ID to answer mapping

metadataobject | null

Additional metadata (clients send this under the 'metadata' key)

Show child attributes

Any of

object

null

submitted_atstring | null

Show child attributes

Any of

string<date-time>

null

Response

200OKDataService_BulkResponseResultDTO

Successful Response

Response fields application/json

totalintegerrequired

successfulintegerrequired

failedintegerrequired

resultsArray<DataService_BulkResponseResultItemDTO>required

Show child attributes

idempotency_keystringrequired

response_idstring | null

Show child attributes

Any of

string

null

statusstringrequired

errorstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Bulk Delete Responses

POST

http://localhost:8002/api/v1/responses/bulk/delete

Bulk delete survey responses.

Supports filtering by survey_id, status, date range, or specific response_ids. Max 10,000 responses per operation. Use dry_run=True to preview the count.

Bulk Delete Responses

curl -X POST 'http://localhost:8002/api/v1/responses/bulk/delete' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false
}'

const body = `{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/bulk/delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/bulk/delete',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false
}

{
  "success_count": 0,
  "failure_count": 0,
  "skipped_count": 0,
  "errors": [],
  "dry_run": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

survey_idstring | null

Show child attributes

Any of

string<uuid>

null

statusArray<DataService_ResponseStatus> | null

Show child attributes

Any of

Array<DataService_ResponseStatus>draftsubmittedcompletedinvalidatedpending_approvalapprovedrejectedterminated

null

start_datestring | null

Show child attributes

Any of

string<date-time>

null

end_datestring | null

Show child attributes

Any of

string<date-time>

null

response_idsArray<string> | null

Show child attributes

Any of

Array<string>

null

dry_runbooleanfalse

Response

200OKDataService_BulkOperationResponseDTO

Successful Response

Response fields application/json

success_countinteger0

failure_countinteger0

skipped_countinteger0

errorsArray<object>

dry_runbooleanfalse

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Bulk Invalidate Responses

POST

http://localhost:8002/api/v1/responses/bulk/invalidate

Bulk invalidate survey responses with a reason.

Supports filtering by survey_id, status, date range, or specific response_ids. Max 10,000 responses per operation. Use dry_run=True to preview the count.

Bulk Invalidate Responses

curl -X POST 'http://localhost:8002/api/v1/responses/bulk/invalidate' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "reason": "string"
}'

const body = `{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "reason": "string"
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/bulk/invalidate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "reason": "string"
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/bulk/invalidate',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "reason": "string"
}

{
  "success_count": 0,
  "failure_count": 0,
  "skipped_count": 0,
  "errors": [],
  "dry_run": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

survey_idstring | null

Show child attributes

Any of

string<uuid>

null

statusArray<DataService_ResponseStatus> | null

Show child attributes

Any of

Array<DataService_ResponseStatus>draftsubmittedcompletedinvalidatedpending_approvalapprovedrejectedterminated

null

start_datestring | null

Show child attributes

Any of

string<date-time>

null

end_datestring | null

Show child attributes

Any of

string<date-time>

null

response_idsArray<string> | null

Show child attributes

Any of

Array<string>

null

dry_runbooleanfalse

reasonstringrequired

Response

200OKDataService_BulkOperationResponseDTO

Successful Response

Response fields application/json

success_countinteger0

failure_countinteger0

skipped_countinteger0

errorsArray<object>

dry_runbooleanfalse

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Bulk Approve Responses

POST

http://localhost:8002/api/v1/responses/bulk/approve

Bulk approve survey responses.

Supports filtering by survey_id, status, date range, or specific response_ids. Max 10,000 responses per operation. Use dry_run=True to preview the count.

Bulk Approve Responses

curl -X POST 'http://localhost:8002/api/v1/responses/bulk/approve' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "notes": "string"
}'

const body = `{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "notes": "string"
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/bulk/approve', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "notes": "string"
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/bulk/approve',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "notes": "string"
}

{
  "success_count": 0,
  "failure_count": 0,
  "skipped_count": 0,
  "errors": [],
  "dry_run": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

survey_idstring | null

Show child attributes

Any of

string<uuid>

null

statusArray<DataService_ResponseStatus> | null

Show child attributes

Any of

Array<DataService_ResponseStatus>draftsubmittedcompletedinvalidatedpending_approvalapprovedrejectedterminated

null

start_datestring | null

Show child attributes

Any of

string<date-time>

null

end_datestring | null

Show child attributes

Any of

string<date-time>

null

response_idsArray<string> | null

Show child attributes

Any of

Array<string>

null

dry_runbooleanfalse

notesstring | null

Show child attributes

Any of

string

null

Response

200OKDataService_BulkOperationResponseDTO

Successful Response

Response fields application/json

success_countinteger0

failure_countinteger0

skipped_countinteger0

errorsArray<object>

dry_runbooleanfalse

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Bulk Update Status Responses

POST

http://localhost:8002/api/v1/responses/bulk/update-status

Bulk update status of survey responses.

Supports filtering by survey_id, status, date range, or specific response_ids. Max 10,000 responses per operation. Use dry_run=True to preview the count.

Bulk Update Status Responses

curl -X POST 'http://localhost:8002/api/v1/responses/bulk/update-status' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "new_status": "string"
}'

const body = `{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "new_status": "string"
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/bulk/update-status', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "new_status": "string"
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/bulk/update-status',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "new_status": "string"
}

{
  "success_count": 0,
  "failure_count": 0,
  "skipped_count": 0,
  "errors": [],
  "dry_run": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

survey_idstring | null

Show child attributes

Any of

string<uuid>

null

statusArray<DataService_ResponseStatus> | null

Show child attributes

Any of

Array<DataService_ResponseStatus>draftsubmittedcompletedinvalidatedpending_approvalapprovedrejectedterminated

null

start_datestring | null

Show child attributes

Any of

string<date-time>

null

end_datestring | null

Show child attributes

Any of

string<date-time>

null

response_idsArray<string> | null

Show child attributes

Any of

Array<string>

null

dry_runbooleanfalse

new_statusstringrequired

Response

200OKDataService_BulkOperationResponseDTO

Successful Response

Response fields application/json

success_countinteger0

failure_countinteger0

skipped_countinteger0

errorsArray<object>

dry_runbooleanfalse

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Data Service / Response Management

Response Management — Data Service

Search Similar

POST

http://localhost:8002/api/v1/responses/search-similar

Find similar responses by survey_id + identifier fields

Search Similar

curl -X POST 'http://localhost:8002/api/v1/responses/search-similar' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "string",
  "respondent_id": "string",
  "respondent_fields": {},
  "gps_coordinates": {}
}'

const body = `{
  "survey_id": "string",
  "respondent_id": "string",
  "respondent_fields": {},
  "gps_coordinates": {}
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/search-similar', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "string",
  "respondent_id": "string",
  "respondent_fields": {},
  "gps_coordinates": {}
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/search-similar',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "string",
  "respondent_id": "string",
  "respondent_fields": {},
  "gps_coordinates": {}
}

{
  "matches": [
    {
      "response_id": "550e8400-e29b-41d4-a716-446655440000",
      "confidence": 0,
      "criteria_breakdown": {},
      "response_details": {}
    }
  ],
  "total": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Any of

survey_idstringrequired

Survey ID to search for duplicates in

respondent_idstring | null

Respondent ID to match

Show child attributes

Any of

string

null

respondent_fieldsobject | null

Other respondent fields for matching

Show child attributes

Any of

object

null

gps_coordinatesobject | null

GPS coordinates for proximity match

Show child attributes

Any of

[key: string]number

null

Response

200OKDataService_SimilaritySearchResponse

Successful Response

Response fields application/json

matchesArray<DataService_SimilarityMatch>required

List of potential duplicates

Show child attributes

response_idstring<uuid>required

ID of the potentially duplicate response

confidencenumberrequired

Confidence score (0-1)

criteria_breakdownobjectrequired

Breakdown of scores per criterion

Show child attributes

[key: string]number

response_detailsobject | null

Additional details about the matched response

Show child attributes

Any of

object

null

totalintegerrequired

Total number of matches found

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Duplicate Groups

GET

http://localhost:8002/api/v1/responses/duplicate-groups

List all duplicate groups (paginated, filterable)

Get Duplicate Groups

curl -X GET 'http://localhost:8002/api/v1/responses/duplicate-groups?skip=0&limit=20'

const response = await fetch('http://localhost:8002/api/v1/responses/duplicate-groups?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/responses/duplicate-groups?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "primary_response_id": "550e8400-e29b-41d4-a716-446655440000",
      "duplicate_response_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "confidence_score": 0,
      "criteria_breakdown": {},
      "status": "string",
      "merged_by": "550e8400-e29b-41d4-a716-446655440000",
      "merged_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring | nullquery

Filter by survey ID

statusstring | nullquery

Filter by status

skipinteger>= 00query

Number of items to skip

limitinteger[1, 100]20query

Number of items per page

Response

200OKDataService_DuplicateGroupListDto

Successful Response

Response fields application/json

itemsArray<DataService_DuplicateGroupDto>required

List of duplicate groups

Show child attributes

idstring<uuid>required

Duplicate group ID

primary_response_idstring<uuid>required

Primary response ID

duplicate_response_idstring<uuid>required

Duplicate response ID

survey_idstring<uuid>required

Survey ID

confidence_scorenumberrequired

Confidence score

criteria_breakdownobjectrequired

Breakdown of scores per criterion

Show child attributes

[key: string]number

statusstringrequired

Status of the duplicate group (flagged, merged, discarded, kept_both)

merged_bystring | null

User who performed the merge

Show child attributes

Any of

string<uuid>

null

merged_atstring | null

When the merge was performed

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

When the duplicate was detected

totalintegerrequired

Total number of duplicate groups

skipintegerrequired

Number of items skipped

limitintegerrequired

Number of items per page

has_nextbooleanrequired

Whether there are more items

has_previousbooleanrequired

Whether there are previous items

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Merge

POST

http://localhost:8002/api/v1/responses/{response_id}/merge

Merge response into another response

Merge

curl -X POST 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/merge' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "target_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "merge_note": "string",
  "conflict_resolutions": {}
}'

const body = `{
  "target_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "merge_note": "string",
  "conflict_resolutions": {}
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/merge', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "target_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "merge_note": "string",
  "conflict_resolutions": {}
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/merge',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "target_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "merge_note": "string",
  "conflict_resolutions": {}
}

{
  "success": true,
  "primary_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "merged_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

target_response_idstring<uuid>required

Response ID to merge into (primary)

merge_notestring | null

Note about the merge

Show child attributes

Any of

string

null

conflict_resolutionsobject | null

Resolutions for conflicting fields (field name -> response ID to keep)

Show child attributes

Any of

[key: string]string

null

Parameters

response_idstring<uuid>requiredpath

Response

200OKDataService_MergeResponseDto

Successful Response

Response fields application/json

successbooleanrequired

Whether the merge was successful

primary_response_idstring<uuid>required

Primary response ID after merge

merged_response_idstring<uuid>required

Response ID that was merged

messagestringrequired

Status message

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Group Status

POST

http://localhost:8002/api/v1/responses/duplicate-groups/{group_id}/status

Update the status of a duplicate group

Update Group Status

curl -X POST 'http://localhost:8002/api/v1/responses/duplicate-groups/550e8400-e29b-41d4-a716-446655440000/status?status=string'

const response = await fetch('http://localhost:8002/api/v1/responses/duplicate-groups/550e8400-e29b-41d4-a716-446655440000/status?status=string', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8002/api/v1/responses/duplicate-groups/550e8400-e29b-41d4-a716-446655440000/status?status=string')
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "primary_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "duplicate_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "confidence_score": 0,
  "criteria_breakdown": {},
  "status": "string",
  "merged_by": "550e8400-e29b-41d4-a716-446655440000",
  "merged_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

group_idstring<uuid>requiredpath

statusstringrequiredquery

New status (flagged, merged, discarded, kept_both)

Response

200OKDataService_DuplicateGroupDto

Successful Response

Response fields application/json

idstring<uuid>required

Duplicate group ID

primary_response_idstring<uuid>required

Primary response ID

duplicate_response_idstring<uuid>required

Duplicate response ID

survey_idstring<uuid>required

Survey ID

confidence_scorenumberrequired

Confidence score

criteria_breakdownobjectrequired

Breakdown of scores per criterion

Show child attributes

[key: string]number

statusstringrequired

Status of the duplicate group (flagged, merged, discarded, kept_both)

merged_bystring | null

User who performed the merge

Show child attributes

Any of

string<uuid>

null

merged_atstring | null

When the merge was performed

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

When the duplicate was detected

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

List Responses

GET

http://localhost:8002/api/v1/responses

List survey responses with filtering and pagination.

Supports filtering by:

Survey ID
Response status
Respondent ID
Date range
Enumerator (submitted_by, enumerator_user_code)
Device (device_id, sync_batch_id)

List Responses

curl -X GET 'http://localhost:8002/api/v1/responses?limit=20&skip=0&sort_by=created_at&sort_order=desc'

const response = await fetch('http://localhost:8002/api/v1/responses?limit=20&skip=0&sort_by=created_at&sort_order=desc', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/responses?limit=20&skip=0&sort_by=created_at&sort_order=desc')
print(response.text)

{
  "items": [
    {
      "id": "string",
      "survey_id": "string",
      "tenant_id": "string",
      "version_id": "string",
      "idempotency_key": "string",
      "interview_id": "string",
      "respondent_id": "string",
      "rid": "string",
      "uid": "string",
      "status": "string",
      "answers": 0,
      "completed_answers": 0,
      "progress_percentage": 0,
      "started_at": "string",
      "submitted_at": "string",
      "completed_at": "string",
      "duration_seconds": 0,
      "ip_address": "string",
      "user_agent": "string",
      "metadata": {},
      "is_valid": true,
      "submitted_by": "string",
      "enumerator_user_code": "string",
      "enumerator_email": "string",
      "enumerator_name": "string",
      "respondent_name": "string",
      "respondent_user_code": "string",
      "device_id": "string",
      "sync_batch_id": "string",
      "synced_at": "string",
      "approved_by": "string",
      "approved_at": "string",
      "approval_notes": "string",
      "rejected_by": "string",
      "rejected_at": "string",
      "rejection_reason": "string",
      "review_flags": {},
      "response_language": "string",
      "is_reconciled": false,
      "reconciled_at": "string",
      "reconciliation_grant_id": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring | nullquery

Filter by survey ID

statusstring | nullquery

Filter by status (draft, submitted, completed, invalidated)

respondent_idstring | nullquery

Filter by respondent ID

from_datestring | nullquery

Filter responses from date (ISO 8601)

to_datestring | nullquery

Filter responses to date (ISO 8601)

submitted_bystring | nullquery

Filter by enumerator user ID

enumerator_user_codestring | nullquery

Filter by enumerator user code

device_idstring | nullquery

Filter by device ID

sync_batch_idstring | nullquery

Filter by sync batch ID

limitinteger[1, 100]20query

Number of results per page

skipinteger>= 00query

Number of results to skip for pagination

sort_bystringcreated_atquery

Sort field

sort_orderstringdescquery

Sort order (asc/desc)

Response

200OKDataService_ResponseListDTO

Successful Response

Response fields application/json

itemsArray<DataService_ResponseDTO>required

Show child attributes

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Submit Response

POST

http://localhost:8002/api/v1/responses

Submit a survey response.

Checks if user has form access
Validates survey is published
Validates response against survey schema
Creates response and answers in transaction
Returns response ID and status

Submit Response

curl -X POST 'http://localhost:8002/api/v1/responses' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "idempotency_key": "string",
  "respondent_id": "string",
  "answers": {},
  "metadata": {},
  "ip_address": "string",
  "user_agent": "string",
  "device_id": "string",
  "sync_batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "submission_mode": "complete",
  "duration_seconds": 0,
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "response_language": "string",
  "is_reconciliation": false,
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000"
}'

const body = `{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "idempotency_key": "string",
  "respondent_id": "string",
  "answers": {},
  "metadata": {},
  "ip_address": "string",
  "user_agent": "string",
  "device_id": "string",
  "sync_batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "submission_mode": "complete",
  "duration_seconds": 0,
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "response_language": "string",
  "is_reconciliation": false,
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000"
}`;

const response = await fetch('http://localhost:8002/api/v1/responses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "idempotency_key": "string",
  "respondent_id": "string",
  "answers": {},
  "metadata": {},
  "ip_address": "string",
  "user_agent": "string",
  "device_id": "string",
  "sync_batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "submission_mode": "complete",
  "duration_seconds": 0,
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "response_language": "string",
  "is_reconciliation": false,
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000"
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "idempotency_key": "string",
  "respondent_id": "string",
  "answers": {},
  "metadata": {},
  "ip_address": "string",
  "user_agent": "string",
  "device_id": "string",
  "sync_batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "submission_mode": "complete",
  "duration_seconds": 0,
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "response_language": "string",
  "is_reconciliation": false,
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "id": "string",
  "survey_id": "string",
  "tenant_id": "string",
  "version_id": "string",
  "idempotency_key": "string",
  "interview_id": "string",
  "respondent_id": "string",
  "rid": "string",
  "uid": "string",
  "status": "string",
  "answers": 0,
  "completed_answers": 0,
  "progress_percentage": 0,
  "started_at": "string",
  "submitted_at": "string",
  "completed_at": "string",
  "duration_seconds": 0,
  "ip_address": "string",
  "user_agent": "string",
  "metadata": {},
  "is_valid": true,
  "submitted_by": "string",
  "enumerator_user_code": "string",
  "enumerator_email": "string",
  "enumerator_name": "string",
  "respondent_name": "string",
  "respondent_user_code": "string",
  "device_id": "string",
  "sync_batch_id": "string",
  "synced_at": "string",
  "approved_by": "string",
  "approved_at": "string",
  "approval_notes": "string",
  "rejected_by": "string",
  "rejected_at": "string",
  "rejection_reason": "string",
  "review_flags": {},
  "response_language": "string",
  "is_reconciled": false,
  "reconciled_at": "string",
  "reconciliation_grant_id": "string",
  "created_at": "string",
  "updated_at": "string"
}

{
  "error": "string",
  "validation_errors": [
    {}
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

survey_idstring<uuid>required

Survey ID

version_idstring | null

Survey version ID

Show child attributes

Any of

string<uuid>

null

idempotency_keystring | null

Unique key for submission idempotency

Show child attributes

Any of

string

null

respondent_idstring | null

Respondent identifier

Show child attributes

Any of

string

null

answersobjectrequired

Question ID to answer mapping

metadataobject | null

Additional metadata (clients send this under the 'metadata' key)

Show child attributes

Any of

object

null

ip_addressstring | null

Client IP address

Show child attributes

Any of

string

null

user_agentstring | null

Client user agent

Show child attributes

Any of

string

null

device_idstring | null

Device identifier (ODK Collect deviceID, CSPro device ID)

Show child attributes

Any of

string

null

sync_batch_idstring | null

Batch ID for grouping offline sync submissions

Show child attributes

Any of

string<uuid>

null

submission_modestring | nullcomplete

Domain-level intent: 'complete' or 'terminated_partial'

Show child attributes

Any of

string

null

duration_secondsinteger | null

Active form filling duration in seconds, excluding paused time

Show child attributes

Any of

integer[0, 2592000]

null

interview_idstring | null

Interview execution ID — links this response to its interview lifecycle

Show child attributes

Any of

string<uuid>

null

interview_ridstring | null

Response RID from interview (generated at interview creation, not at submission)

Show child attributes

Any of

string

null

collected_atstring | null

Device-reported capture time (ISO-8601). Source of truth for the schedule window on offline submissions — a response collected on-device before close_at syncs even after the survey is auto-archived server-side.

Show child attributes

Any of

string<date-time>

null

response_languagestring | null

Language code used for this submission (e.g., 'en', 'es', 'fr')

Show child attributes

Any of

string

null

is_reconciliationbooleanfalse

Flag indicating this submission is a server-authorized reconciliation of work predating revocation (R22)

reconciliation_grant_idstring | null

Historical form access grant ID authorizing this reconciliation

Show child attributes

Any of

string<uuid>

null

Response

201CreatedDataService_ResponseDTO

Successful Response

Response fields application/json

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

400Bad RequestDataService_ResponseValidationErrorDTO

Validation error

Response fields application/json

errorstringrequired

validation_errorsArray<object>required

403Forbidden

Access denied

404Not Found

Survey not found

409Conflict

Duplicate response

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get RID sequential counter

GET

http://localhost:8002/api/v1/responses/response-counters

Get the current sequential RID counter for a user + survey. Returns 0 when no RID has been generated yet. Clients increment the returned value locally to build the next RID.

Get RID sequential counter

curl -X GET 'http://localhost:8002/api/v1/responses/response-counters?survey_id=550e8400-e29b-41d4-a716-446655440000&user_code=string'

const response = await fetch('http://localhost:8002/api/v1/responses/response-counters?survey_id=550e8400-e29b-41d4-a716-446655440000&user_code=string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/responses/response-counters?survey_id=550e8400-e29b-41d4-a716-446655440000&user_code=string')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredquery

Survey ID

user_codestringrequiredquery

Enumerator user code (6 chars)

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get latest response by respondent ID

GET

http://localhost:8002/api/v1/responses/by-respondent-id/{survey_id}

Get the latest submitted/completed response for a respondent in a survey.

Get latest response by respondent ID

curl -X GET 'http://localhost:8002/api/v1/responses/by-respondent-id/550e8400-e29b-41d4-a716-446655440000?respondent_id=string'

const response = await fetch('http://localhost:8002/api/v1/responses/by-respondent-id/550e8400-e29b-41d4-a716-446655440000?respondent_id=string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/responses/by-respondent-id/550e8400-e29b-41d4-a716-446655440000?respondent_id=string')
print(response.text)

{
  "id": "string",
  "survey_id": "string",
  "tenant_id": "string",
  "version_id": "string",
  "idempotency_key": "string",
  "interview_id": "string",
  "respondent_id": "string",
  "rid": "string",
  "uid": "string",
  "status": "string",
  "answers": 0,
  "completed_answers": 0,
  "progress_percentage": 0,
  "started_at": "string",
  "submitted_at": "string",
  "completed_at": "string",
  "duration_seconds": 0,
  "ip_address": "string",
  "user_agent": "string",
  "metadata": {},
  "is_valid": true,
  "submitted_by": "string",
  "enumerator_user_code": "string",
  "enumerator_email": "string",
  "enumerator_name": "string",
  "respondent_name": "string",
  "respondent_user_code": "string",
  "device_id": "string",
  "sync_batch_id": "string",
  "synced_at": "string",
  "approved_by": "string",
  "approved_at": "string",
  "approval_notes": "string",
  "rejected_by": "string",
  "rejected_at": "string",
  "rejection_reason": "string",
  "review_flags": {},
  "response_language": "string",
  "is_reconciled": false,
  "reconciled_at": "string",
  "reconciliation_grant_id": "string",
  "created_at": "string",
  "updated_at": "string",
  "answers_list": []
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

respondent_idstringrequiredquery

Respondent identifier

Response

200OKDataService_ResponseDetailDTO

Successful Response

Response fields application/json

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

answers_listArray<DataService_EnrichedAnswerDTO>

Show child attributes

question_idstringrequired

question_typestringrequired

valuestring | null

Show child attributes

Any of

string

null

value_jsonany | null

Show child attributes

Any of

any

null

presigned_urlstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get response by unique ID

GET

http://localhost:8002/api/v1/responses/by-unique-id/{survey_id}

Get a response matching the unique_id (uid) value for a survey.

Get response by unique ID

curl -X GET 'http://localhost:8002/api/v1/responses/by-unique-id/550e8400-e29b-41d4-a716-446655440000?unique_id=string'

const response = await fetch('http://localhost:8002/api/v1/responses/by-unique-id/550e8400-e29b-41d4-a716-446655440000?unique_id=string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/responses/by-unique-id/550e8400-e29b-41d4-a716-446655440000?unique_id=string')
print(response.text)

{
  "id": "string",
  "survey_id": "string",
  "tenant_id": "string",
  "version_id": "string",
  "idempotency_key": "string",
  "interview_id": "string",
  "respondent_id": "string",
  "rid": "string",
  "uid": "string",
  "status": "string",
  "answers": 0,
  "completed_answers": 0,
  "progress_percentage": 0,
  "started_at": "string",
  "submitted_at": "string",
  "completed_at": "string",
  "duration_seconds": 0,
  "ip_address": "string",
  "user_agent": "string",
  "metadata": {},
  "is_valid": true,
  "submitted_by": "string",
  "enumerator_user_code": "string",
  "enumerator_email": "string",
  "enumerator_name": "string",
  "respondent_name": "string",
  "respondent_user_code": "string",
  "device_id": "string",
  "sync_batch_id": "string",
  "synced_at": "string",
  "approved_by": "string",
  "approved_at": "string",
  "approval_notes": "string",
  "rejected_by": "string",
  "rejected_at": "string",
  "rejection_reason": "string",
  "review_flags": {},
  "response_language": "string",
  "is_reconciled": false,
  "reconciled_at": "string",
  "reconciliation_grant_id": "string",
  "created_at": "string",
  "updated_at": "string",
  "answers_list": []
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

unique_idstringrequiredquery

Unique identifier value from uid column

Response

200OKDataService_ResponseDetailDTO

Successful Response

Response fields application/json

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

answers_listArray<DataService_EnrichedAnswerDTO>

Show child attributes

question_idstringrequired

question_typestringrequired

valuestring | null

Show child attributes

Any of

string

null

value_jsonany | null

Show child attributes

Any of

any

null

presigned_urlstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get enumerator statistics for a survey

GET

http://localhost:8002/api/v1/responses/enumerator-stats

Get per-enumerator submission counts, rejection rates, and quality metrics.

Get enumerator statistics for a survey

curl -X GET 'http://localhost:8002/api/v1/responses/enumerator-stats?survey_id=550e8400-e29b-41d4-a716-446655440000&limit=20&offset=0'

const response = await fetch('http://localhost:8002/api/v1/responses/enumerator-stats?survey_id=550e8400-e29b-41d4-a716-446655440000&limit=20&offset=0', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/responses/enumerator-stats?survey_id=550e8400-e29b-41d4-a716-446655440000&limit=20&offset=0')
print(response.text)

{
  "items": [
    {
      "user_id": "string",
      "survey_id": "string",
      "total_submissions": 0,
      "total_rejected": 0,
      "rejection_rate": 0,
      "avg_duration_seconds": 0,
      "duration_count": 0,
      "avg_quality_score": 0,
      "last_submission_at": "string",
      "enumerator_name": "string",
      "enumerator_user_code": "string",
      "enumerator_email": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredquery

Survey ID to get stats for

user_idstring | nullquery

Filter by specific enumerator

limitinteger[1, 100]20query

offsetinteger>= 00query

Response

200OKDataService_EnumeratorStatsListDTO

Successful Response

Response fields application/json

itemsArray<DataService_EnumeratorStatsDTO>required

Show child attributes

user_idstringrequired

survey_idstringrequired

total_submissionsintegerrequired

total_rejectedintegerrequired

rejection_ratenumberrequired

avg_duration_secondsnumber | null

Show child attributes

Any of

number

null

duration_countinteger0

avg_quality_scorenumber | null

Show child attributes

Any of

number

null

last_submission_atstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

List Response Changes

GET

http://localhost:8002/api/v1/responses/changes

Durable, resumable feed of this enumerator's own response changes (E1b).

Scope is fixed to the caller's tenant and the caller as the original submitting user (submitted_by == current_user.id). It deliberately does NOT use resolve_response_scope and has no full:access bypass: even a platform admin only ever sees changes for responses they personally submitted.

Changes are logged transactionally by a DB trigger; the cursor is an xid8 watermark with a snapshot horizon so pages never overlap and never skip an in-flight transaction. No answer values are returned.

List Response Changes

curl -X GET 'http://localhost:8002/api/v1/responses/changes?since=0&limit=100'

const response = await fetch('http://localhost:8002/api/v1/responses/changes?since=0&limit=100', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/responses/changes?since=0&limit=100')
print(response.text)

{
  "items": [
    {
      "response_id": "string",
      "survey_id": "string",
      "change_type": "string",
      "changed_fields": [
        "string"
      ],
      "changed_at": "string"
    }
  ],
  "next_watermark": "string",
  "has_more": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

sincestring0query

Watermark (transaction id, decimal text) from a previous page

limitinteger[1, 1000]100query

Maximum number of changes per page

Response

200OKDataService_ResponseChangeFeedDTO

Successful Response

Response fields application/json

itemsArray<DataService_ResponseChangeDTO>required

Show child attributes

A single response change. Deliberately carries no answer values.

response_idstringrequired

survey_idstring | null

Show child attributes

Any of

string

null

change_typestringrequired

changed_fieldsArray<string> | null

Show child attributes

Any of

Array<string>

null

changed_atstringrequired

next_watermarkstringrequired

has_morebooleanrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Response

GET

http://localhost:8002/api/v1/responses/{response_id}

Get a single response by ID with optional answer details.

Get Response

curl -X GET 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000?include_answers=true'

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000?include_answers=true', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000?include_answers=true')
print(response.text)

{
  "id": "string",
  "survey_id": "string",
  "tenant_id": "string",
  "version_id": "string",
  "idempotency_key": "string",
  "interview_id": "string",
  "respondent_id": "string",
  "rid": "string",
  "uid": "string",
  "status": "string",
  "answers": 0,
  "completed_answers": 0,
  "progress_percentage": 0,
  "started_at": "string",
  "submitted_at": "string",
  "completed_at": "string",
  "duration_seconds": 0,
  "ip_address": "string",
  "user_agent": "string",
  "metadata": {},
  "is_valid": true,
  "submitted_by": "string",
  "enumerator_user_code": "string",
  "enumerator_email": "string",
  "enumerator_name": "string",
  "respondent_name": "string",
  "respondent_user_code": "string",
  "device_id": "string",
  "sync_batch_id": "string",
  "synced_at": "string",
  "approved_by": "string",
  "approved_at": "string",
  "approval_notes": "string",
  "rejected_by": "string",
  "rejected_at": "string",
  "rejection_reason": "string",
  "review_flags": {},
  "response_language": "string",
  "is_reconciled": false,
  "reconciled_at": "string",
  "reconciliation_grant_id": "string",
  "created_at": "string",
  "updated_at": "string",
  "answers_list": []
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

response_idstring<uuid>requiredpath

include_answersbooleantruequery

Include answer details

Response

200OKDataService_ResponseDetailDTO

Successful Response

Response fields application/json

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

answers_listArray<DataService_EnrichedAnswerDTO>

Show child attributes

question_idstringrequired

question_typestringrequired

valuestring | null

Show child attributes

Any of

string

null

value_jsonany | null

Show child attributes

Any of

any

null

presigned_urlstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Response

PUT

http://localhost:8002/api/v1/responses/{response_id}

Update response metadata (only allowed for draft/submitted responses).

Cannot modify completed or invalidated responses.

Update Response

curl -X PUT 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "respondent_id": "string",
  "metadata": {},
  "status": "string"
}'

const body = `{
  "respondent_id": "string",
  "metadata": {},
  "status": "string"
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "respondent_id": "string",
  "metadata": {},
  "status": "string"
}'''

response = requests.put(
    'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "respondent_id": "string",
  "metadata": {},
  "status": "string"
}

{
  "id": "string",
  "survey_id": "string",
  "tenant_id": "string",
  "version_id": "string",
  "idempotency_key": "string",
  "interview_id": "string",
  "respondent_id": "string",
  "rid": "string",
  "uid": "string",
  "status": "string",
  "answers": 0,
  "completed_answers": 0,
  "progress_percentage": 0,
  "started_at": "string",
  "submitted_at": "string",
  "completed_at": "string",
  "duration_seconds": 0,
  "ip_address": "string",
  "user_agent": "string",
  "metadata": {},
  "is_valid": true,
  "submitted_by": "string",
  "enumerator_user_code": "string",
  "enumerator_email": "string",
  "enumerator_name": "string",
  "respondent_name": "string",
  "respondent_user_code": "string",
  "device_id": "string",
  "sync_batch_id": "string",
  "synced_at": "string",
  "approved_by": "string",
  "approved_at": "string",
  "approval_notes": "string",
  "rejected_by": "string",
  "rejected_at": "string",
  "rejection_reason": "string",
  "review_flags": {},
  "response_language": "string",
  "is_reconciled": false,
  "reconciled_at": "string",
  "reconciliation_grant_id": "string",
  "created_at": "string",
  "updated_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

respondent_idstring | null

Show child attributes

Any of

string

null

metadataobject | null

Additional metadata (clients send this under the 'metadata' key)

Show child attributes

Any of

object

null

statusstring | null

Show child attributes

Any of

string

null

Parameters

response_idstring<uuid>requiredpath

Response

200OKDataService_ResponseDTO

Successful Response

Response fields application/json

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Response

DELETE

http://localhost:8002/api/v1/responses/{response_id}

Delete a response and all its answers.

Delete Response

curl -X DELETE 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

response_idstring<uuid>requiredpath

Response

204No Content

Successful Response

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Invalidate Response

POST

http://localhost:8002/api/v1/responses/{response_id}/invalidate

Mark a response as invalidated with optional error messages.

Invalidate Response

curl -X POST 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/invalidate' \
  -H 'Content-Type: application/json' \
  --data-raw '[
  "string"
]'

const body = `[
  "string"
]`;

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/invalidate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''[
  "string"
]'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/invalidate',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

[
  "string"
]

{
  "id": "string",
  "survey_id": "string",
  "tenant_id": "string",
  "version_id": "string",
  "idempotency_key": "string",
  "interview_id": "string",
  "respondent_id": "string",
  "rid": "string",
  "uid": "string",
  "status": "string",
  "answers": 0,
  "completed_answers": 0,
  "progress_percentage": 0,
  "started_at": "string",
  "submitted_at": "string",
  "completed_at": "string",
  "duration_seconds": 0,
  "ip_address": "string",
  "user_agent": "string",
  "metadata": {},
  "is_valid": true,
  "submitted_by": "string",
  "enumerator_user_code": "string",
  "enumerator_email": "string",
  "enumerator_name": "string",
  "respondent_name": "string",
  "respondent_user_code": "string",
  "device_id": "string",
  "sync_batch_id": "string",
  "synced_at": "string",
  "approved_by": "string",
  "approved_at": "string",
  "approval_notes": "string",
  "rejected_by": "string",
  "rejected_at": "string",
  "rejection_reason": "string",
  "review_flags": {},
  "response_language": "string",
  "is_reconciled": false,
  "reconciled_at": "string",
  "reconciliation_grant_id": "string",
  "created_at": "string",
  "updated_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Any of

Array<string>

null

Parameters

response_idstring<uuid>requiredpath

Response

200OKDataService_ResponseDTO

Successful Response

Response fields application/json

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Edit Response

PATCH

http://localhost:8002/api/v1/responses/{response_id}/edit

Edit a submitted/completed response. Maintains full audit trail.

Blocked for DRAFT responses (use PUT instead)
Blocked for INVALIDATED responses
Validates new answers against survey schema
Saves previous answers to edit history
Publishes response.edited event

Edit Response

curl -X PATCH 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/edit' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "answers": {},
  "reason": "string"
}'

const body = `{
  "answers": {},
  "reason": "string"
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/edit', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "answers": {},
  "reason": "string"
}'''

response = requests.patch(
    'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/edit',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "answers": {},
  "reason": "string"
}

{
  "success": true,
  "edit_id": "550e8400-e29b-41d4-a716-446655440000",
  "response": {
    "id": "string",
    "survey_id": "string",
    "tenant_id": "string",
    "version_id": "string",
    "idempotency_key": "string",
    "interview_id": "string",
    "respondent_id": "string",
    "rid": "string",
    "uid": "string",
    "status": "string",
    "answers": 0,
    "completed_answers": 0,
    "progress_percentage": 0,
    "started_at": "string",
    "submitted_at": "string",
    "completed_at": "string",
    "duration_seconds": 0,
    "ip_address": "string",
    "user_agent": "string",
    "metadata": {},
    "is_valid": true,
    "submitted_by": "string",
    "enumerator_user_code": "string",
    "enumerator_email": "string",
    "enumerator_name": "string",
    "respondent_name": "string",
    "respondent_user_code": "string",
    "device_id": "string",
    "sync_batch_id": "string",
    "synced_at": "string",
    "approved_by": "string",
    "approved_at": "string",
    "approval_notes": "string",
    "rejected_by": "string",
    "rejected_at": "string",
    "rejection_reason": "string",
    "review_flags": {},
    "response_language": "string",
    "is_reconciled": false,
    "reconciled_at": "string",
    "reconciliation_grant_id": "string",
    "created_at": "string",
    "updated_at": "string",
    "answers_list": []
  },
  "changes_count": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

answersobjectrequired

Question ID to answer mapping

reasonstring | null

Reason for edit

Show child attributes

Any of

string

null

Parameters

response_idstring<uuid>requiredpath

Response

200OKDataService_ResponseEditResponse

Successful Response

Response fields application/json

successbooleanrequired

edit_idstring<uuid>required

responseDataService_ResponseDetailDTOrequired

Show child attributes

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

answers_listArray<DataService_EnrichedAnswerDTO>

Show child attributes

question_idstringrequired

question_typestringrequired

valuestring | null

Show child attributes

Any of

string

null

value_jsonany | null

Show child attributes

Any of

any

null

presigned_urlstring | null

Show child attributes

Any of

string

null

changes_countintegerrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Response Edits

GET

http://localhost:8002/api/v1/responses/{response_id}/edits

Get edit history for a specific response.

Get Response Edits

curl -X GET 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/edits'

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/edits', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/edits')
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "edited_at": "2024-01-15T09:30:00Z",
      "edited_by": "550e8400-e29b-41d4-a716-446655440000",
      "reason": "string",
      "changes_count": 0
    }
  ],
  "total": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

response_idstring<uuid>requiredpath

Response

200OKDataService_ResponseEditHistoryListDTO

Successful Response

Response fields application/json

itemsArray<DataService_ResponseEditHistoryDTO>required

Show child attributes

idstring<uuid>required

edited_atstring<date-time>required

edited_bystring<uuid>required

reasonstring | null

Show child attributes

Any of

string

null

changes_countintegerrequired

totalintegerrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Submit Response For Approval

POST

http://localhost:8002/api/v1/responses/{response_id}/submit-for-approval

Submit a response for approval.

Transitions: SUBMITTED or REJECTED → PENDING_APPROVAL Permission: RESPONSE_READ_AND_WRITE_ONLY

Submit Response For Approval

curl -X POST 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/submit-for-approval'

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/submit-for-approval', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/submit-for-approval')
print(response.text)

{
  "success": true,
  "message": "string",
  "response": {
    "id": "string",
    "survey_id": "string",
    "tenant_id": "string",
    "version_id": "string",
    "idempotency_key": "string",
    "interview_id": "string",
    "respondent_id": "string",
    "rid": "string",
    "uid": "string",
    "status": "string",
    "answers": 0,
    "completed_answers": 0,
    "progress_percentage": 0,
    "started_at": "string",
    "submitted_at": "string",
    "completed_at": "string",
    "duration_seconds": 0,
    "ip_address": "string",
    "user_agent": "string",
    "metadata": {},
    "is_valid": true,
    "submitted_by": "string",
    "enumerator_user_code": "string",
    "enumerator_email": "string",
    "enumerator_name": "string",
    "respondent_name": "string",
    "respondent_user_code": "string",
    "device_id": "string",
    "sync_batch_id": "string",
    "synced_at": "string",
    "approved_by": "string",
    "approved_at": "string",
    "approval_notes": "string",
    "rejected_by": "string",
    "rejected_at": "string",
    "rejection_reason": "string",
    "review_flags": {},
    "response_language": "string",
    "is_reconciled": false,
    "reconciled_at": "string",
    "reconciliation_grant_id": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

response_idstring<uuid>requiredpath

Response

200OKDataService_ApprovalActionResponse

Successful Response

Response fields application/json

successbooleanrequired

messagestringrequired

responseDataService_ResponseDTOrequired

Show child attributes

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Approve Response

POST

http://localhost:8002/api/v1/responses/{response_id}/approve

Approve a response that is pending approval.

Transitions: PENDING_APPROVAL → APPROVED Permission: RESPONSE_APPROVE

Sends approval notification to the respondent.

Approve Response

curl -X POST 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/approve' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "notes": "string"
}'

const body = `{
  "notes": "string"
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/approve', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "notes": "string"
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/approve',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "notes": "string"
}

{
  "success": true,
  "message": "string",
  "response": {
    "id": "string",
    "survey_id": "string",
    "tenant_id": "string",
    "version_id": "string",
    "idempotency_key": "string",
    "interview_id": "string",
    "respondent_id": "string",
    "rid": "string",
    "uid": "string",
    "status": "string",
    "answers": 0,
    "completed_answers": 0,
    "progress_percentage": 0,
    "started_at": "string",
    "submitted_at": "string",
    "completed_at": "string",
    "duration_seconds": 0,
    "ip_address": "string",
    "user_agent": "string",
    "metadata": {},
    "is_valid": true,
    "submitted_by": "string",
    "enumerator_user_code": "string",
    "enumerator_email": "string",
    "enumerator_name": "string",
    "respondent_name": "string",
    "respondent_user_code": "string",
    "device_id": "string",
    "sync_batch_id": "string",
    "synced_at": "string",
    "approved_by": "string",
    "approved_at": "string",
    "approval_notes": "string",
    "rejected_by": "string",
    "rejected_at": "string",
    "rejection_reason": "string",
    "review_flags": {},
    "response_language": "string",
    "is_reconciled": false,
    "reconciled_at": "string",
    "reconciliation_grant_id": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

notesstring | null

Optional approval notes

Show child attributes

Any of

string

null

Parameters

response_idstring<uuid>requiredpath

Response

200OKDataService_ApprovalActionResponse

Successful Response

Response fields application/json

successbooleanrequired

messagestringrequired

responseDataService_ResponseDTOrequired

Show child attributes

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Reject Response

POST

http://localhost:8002/api/v1/responses/{response_id}/reject

Reject a response that is pending approval.

Transitions: PENDING_APPROVAL → REJECTED Permission: RESPONSE_APPROVE

Requires a reason for rejection. Sends rejection notification with reason to the respondent.

Reject Response

curl -X POST 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/reject' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "reason": "string",
  "flags": {}
}'

const body = `{
  "reason": "string",
  "flags": {}
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/reject', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "reason": "string",
  "flags": {}
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/reject',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "reason": "string",
  "flags": {}
}

{
  "success": true,
  "message": "string",
  "response": {
    "id": "string",
    "survey_id": "string",
    "tenant_id": "string",
    "version_id": "string",
    "idempotency_key": "string",
    "interview_id": "string",
    "respondent_id": "string",
    "rid": "string",
    "uid": "string",
    "status": "string",
    "answers": 0,
    "completed_answers": 0,
    "progress_percentage": 0,
    "started_at": "string",
    "submitted_at": "string",
    "completed_at": "string",
    "duration_seconds": 0,
    "ip_address": "string",
    "user_agent": "string",
    "metadata": {},
    "is_valid": true,
    "submitted_by": "string",
    "enumerator_user_code": "string",
    "enumerator_email": "string",
    "enumerator_name": "string",
    "respondent_name": "string",
    "respondent_user_code": "string",
    "device_id": "string",
    "sync_batch_id": "string",
    "synced_at": "string",
    "approved_by": "string",
    "approved_at": "string",
    "approval_notes": "string",
    "rejected_by": "string",
    "rejected_at": "string",
    "rejection_reason": "string",
    "review_flags": {},
    "response_language": "string",
    "is_reconciled": false,
    "reconciled_at": "string",
    "reconciliation_grant_id": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

reasonstringrequired

Required rejection reason

flagsobjectrequired

Required review flags to persist atomically with the rejection. At least one flag must have checked=true. There is no fallback to previously stored flags.

Show child attributes

[key: string]DataService_ReviewFlag

Show child attributes

checkedbooleanfalse

notestring | null

Show child attributes

Any of

string

null

Parameters

response_idstring<uuid>requiredpath

Response

200OKDataService_ApprovalActionResponse

Successful Response

Response fields application/json

successbooleanrequired

messagestringrequired

responseDataService_ResponseDTOrequired

Show child attributes

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Correct Response

POST

http://localhost:8002/api/v1/responses/{response_id}/correct

Correct a rejected response and resubmit it for approval (E1a).

Correction actor is the ORIGINAL submitting enumerator only, enforced by an unconditional submitted_by == current_user.id check that is independent of (and cannot be bypassed by) permissions such as full:access.

Only supervisor-flagged (checked: true) questions may be changed; all other answers are preserved. The whole flow runs in one transaction: ownership → Idempotency-Key requirement → advisory lock → replay lookup → status → flagged validation → schema validation → answer apply → edit history → status transition (REJECTED → PENDING_APPROVAL) → durable idempotency record. No webhook/outbox events are published in this phase.

Correct Response

curl -X POST 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/correct' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "answers": {},
  "reason": "string"
}'

const body = `{
  "answers": {},
  "reason": "string"
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/correct', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "answers": {},
  "reason": "string"
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/correct',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "answers": {},
  "reason": "string"
}

{
  "success": true,
  "replayed": false,
  "response_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "string",
  "edit_id": "550e8400-e29b-41d4-a716-446655440000",
  "edit_count": 0,
  "changed_questions": [
    "string"
  ],
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Enumerator correction of a rejected response.

answers must contain only questions the supervisor flagged as checked. Supplying answers for unflagged questions is rejected with 422. Questions omitted here are left unchanged.

answersobjectrequired

Corrected answers for flagged questions only

reasonstring | null

Reason for correction

Show child attributes

Any of

string

null

Parameters

response_idstring<uuid>requiredpath

Response

200OKDataService_ResponseCorrectionResponse

Successful Response

Response fields application/json

successbooleantrue

replayedbooleanfalse

response_idstring<uuid>required

statusstringrequired

edit_idstring | null

Show child attributes

Any of

string<uuid>

null

edit_countintegerrequired

changed_questionsArray<string>required

updated_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Complete Response

POST

http://localhost:8002/api/v1/responses/{response_id}/complete

Mark a response as completed.

Transitions: DRAFT, SUBMITTED, or APPROVED → COMPLETED Permission: RESPONSE_READ_AND_WRITE_ONLY

Complete Response

curl -X POST 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/complete'

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/complete', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/complete')
print(response.text)

{
  "success": true,
  "message": "string",
  "response": {
    "id": "string",
    "survey_id": "string",
    "tenant_id": "string",
    "version_id": "string",
    "idempotency_key": "string",
    "interview_id": "string",
    "respondent_id": "string",
    "rid": "string",
    "uid": "string",
    "status": "string",
    "answers": 0,
    "completed_answers": 0,
    "progress_percentage": 0,
    "started_at": "string",
    "submitted_at": "string",
    "completed_at": "string",
    "duration_seconds": 0,
    "ip_address": "string",
    "user_agent": "string",
    "metadata": {},
    "is_valid": true,
    "submitted_by": "string",
    "enumerator_user_code": "string",
    "enumerator_email": "string",
    "enumerator_name": "string",
    "respondent_name": "string",
    "respondent_user_code": "string",
    "device_id": "string",
    "sync_batch_id": "string",
    "synced_at": "string",
    "approved_by": "string",
    "approved_at": "string",
    "approval_notes": "string",
    "rejected_by": "string",
    "rejected_at": "string",
    "rejection_reason": "string",
    "review_flags": {},
    "response_language": "string",
    "is_reconciled": false,
    "reconciled_at": "string",
    "reconciliation_grant_id": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

response_idstring<uuid>requiredpath

Response

200OKDataService_ApprovalActionResponse

Successful Response

Response fields application/json

successbooleanrequired

messagestringrequired

responseDataService_ResponseDTOrequired

Show child attributes

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Pending Approval Count

GET

http://localhost:8002/api/v1/responses/pending-approval/count

Get count of responses pending approval for a given survey.

Permission: RESPONSE_APPROVE

Get Pending Approval Count

curl -X GET 'http://localhost:8002/api/v1/responses/pending-approval/count?survey_id=550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8002/api/v1/responses/pending-approval/count?survey_id=550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/responses/pending-approval/count?survey_id=550e8400-e29b-41d4-a716-446655440000')
print(response.text)

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "count": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredquery

Survey ID

Response

200OKDataService_PendingApprovalCountDTO

Successful Response

Response fields application/json

survey_idstring<uuid>required

countintegerrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Review Flags

PUT

http://localhost:8002/api/v1/responses/{response_id}/review-flags

Update review flags for a response pending approval.

Allows the reviewer to flag individual questions that need modification and add review notes. These flags are visible to the respondent when the response is rejected.

Update Review Flags

curl -X PUT 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/review-flags' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "flags": {}
}'

const body = `{
  "flags": {}
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/review-flags', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "flags": {}
}'''

response = requests.put(
    'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/review-flags',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "flags": {}
}

{
  "id": "string",
  "survey_id": "string",
  "tenant_id": "string",
  "version_id": "string",
  "idempotency_key": "string",
  "interview_id": "string",
  "respondent_id": "string",
  "rid": "string",
  "uid": "string",
  "status": "string",
  "answers": 0,
  "completed_answers": 0,
  "progress_percentage": 0,
  "started_at": "string",
  "submitted_at": "string",
  "completed_at": "string",
  "duration_seconds": 0,
  "ip_address": "string",
  "user_agent": "string",
  "metadata": {},
  "is_valid": true,
  "submitted_by": "string",
  "enumerator_user_code": "string",
  "enumerator_email": "string",
  "enumerator_name": "string",
  "respondent_name": "string",
  "respondent_user_code": "string",
  "device_id": "string",
  "sync_batch_id": "string",
  "synced_at": "string",
  "approved_by": "string",
  "approved_at": "string",
  "approval_notes": "string",
  "rejected_by": "string",
  "rejected_at": "string",
  "rejection_reason": "string",
  "review_flags": {},
  "response_language": "string",
  "is_reconciled": false,
  "reconciled_at": "string",
  "reconciliation_grant_id": "string",
  "created_at": "string",
  "updated_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

flagsobject

Question ID to review flag mapping

Show child attributes

[key: string]DataService_ReviewFlag

Show child attributes

checkedbooleanfalse

notestring | null

Show child attributes

Any of

string

null

Parameters

response_idstring<uuid>requiredpath

Response

200OKDataService_ResponseDTO

Successful Response

Response fields application/json

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get response statistics for a survey (internal)

GET

http://localhost:8002/api/v1/responses/survey-stats/{survey_id}

Return response counts grouped by status for a given survey. Used internally by survey-service for publish guardrails. Requires X-Tenant-ID header for multi-tenant routing.

Get response statistics for a survey (internal)

curl -X GET 'http://localhost:8002/api/v1/responses/survey-stats/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8002/api/v1/responses/survey-stats/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/responses/survey-stats/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Validate a list of response IDs (removes orphans)

POST

http://localhost:8002/api/v1/responses/{survey_id}/validate-ids

Takes a list of response UUIDs and returns only those that exist and belong to the current survey/tenant. Used to identify orphaned media attachments.

Validate a list of response IDs (removes orphans)

curl -X POST 'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/validate-ids' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}'

const body = `{
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}`;

const response = await fetch('http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/validate-ids', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}'''

response = requests.post(
    'http://localhost:8002/api/v1/responses/550e8400-e29b-41d4-a716-446655440000/validate-ids',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

{
  "valid_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

response_idsArray<string>required

Parameters

survey_idstring<uuid>requiredpath

Response

200OKDataService_ValidateIdsResponse

Successful Response

Response fields application/json

valid_idsArray<string>required

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Data Service / Data Export

Data Export — Data Service

Export Responses

POST

http://localhost:8002/api/v1/export/responses

Export survey responses in CSV, Excel, or JSON format. Returns a streaming response with the exported data.

Export Responses

curl -X POST 'http://localhost:8002/api/v1/export/responses' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "format": "csv",
  "status": "string",
  "from_date": "2024-01-15T09:30:00Z",
  "to_date": "2024-01-15T09:30:00Z",
  "respondent_id": "string",
  "include_metadata": true,
  "include_answers": true,
  "version_id": "string",
  "language": "string"
}'

const body = `{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "format": "csv",
  "status": "string",
  "from_date": "2024-01-15T09:30:00Z",
  "to_date": "2024-01-15T09:30:00Z",
  "respondent_id": "string",
  "include_metadata": true,
  "include_answers": true,
  "version_id": "string",
  "language": "string"
}`;

const response = await fetch('http://localhost:8002/api/v1/export/responses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "format": "csv",
  "status": "string",
  "from_date": "2024-01-15T09:30:00Z",
  "to_date": "2024-01-15T09:30:00Z",
  "respondent_id": "string",
  "include_metadata": true,
  "include_answers": true,
  "version_id": "string",
  "language": "string"
}'''

response = requests.post(
    'http://localhost:8002/api/v1/export/responses',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "format": "csv",
  "status": "string",
  "from_date": "2024-01-15T09:30:00Z",
  "to_date": "2024-01-15T09:30:00Z",
  "respondent_id": "string",
  "include_metadata": true,
  "include_answers": true,
  "version_id": "string",
  "language": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

survey_idstring<uuid>required

Survey ID to export

formatstringcsv

Export format: csv, xlsx, json, dta, sav

statusstring | null

Filter by response status

Show child attributes

Any of

string

null

from_datestring | null

Filter from date

Show child attributes

Any of

string<date-time>

null

to_datestring | null

Filter to date

Show child attributes

Any of

string<date-time>

null

respondent_idstring | null

Filter by respondent

Show child attributes

Any of

string

null

include_metadatabooleantrue

Include response metadata

include_answersbooleantrue

Include answer data

version_idstring | null

Survey version ID for schema labels (uses latest if not set)

Show child attributes

Any of

string

null

languagestring | null

Language code for translated labels (e.g., 'es', 'fr')

Show child attributes

Any of

string

null

Response

200OK

Successful Response

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Export Responses Stream

GET

http://localhost:8002/api/v1/export/responses/stream

Stream export responses (GET version for simple downloads).

Export Responses Stream

curl -X GET 'http://localhost:8002/api/v1/export/responses/stream?survey_id=550e8400-e29b-41d4-a716-446655440000&format=csv&include_metadata=true&include_answers=true'

const response = await fetch('http://localhost:8002/api/v1/export/responses/stream?survey_id=550e8400-e29b-41d4-a716-446655440000&format=csv&include_metadata=true&include_answers=true', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/export/responses/stream?survey_id=550e8400-e29b-41d4-a716-446655440000&format=csv&include_metadata=true&include_answers=true')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredquery

Survey ID

formatstringcsvquery

Export format

statusstring | nullquery

Filter by status

from_datestring | nullquery

From date

to_datestring | nullquery

To date

include_metadatabooleantruequery

include_answersbooleantruequery

languagestring | nullquery

Language code for translated labels

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Media Export Status

GET

http://localhost:8002/api/v1/export/media/{request_id}/status

Poll the status of a background media export job.

Get Media Export Status

curl -X GET 'http://localhost:8002/api/v1/export/media/string/status'

const response = await fetch('http://localhost:8002/api/v1/export/media/string/status', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/export/media/string/status')
print(response.text)

{
  "request_id": "string",
  "task_status": "string",
  "result": {},
  "error": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

request_idstringrequiredpath

Response

200OKDataService_MediaExportStatusDTO

Successful Response

Response fields application/json

request_idstringrequired

task_statusstringrequired

resultobject | null

Show child attributes

Any of

object

null

errorstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Export Survey Csv

GET

http://localhost:8002/api/v1/export/survey/{survey_id}/csv

Quick CSV export for a survey.

Export Survey Csv

curl -X GET 'http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/csv'

const response = await fetch('http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/csv', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/csv')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

statusstring | nullquery

languagestring | nullquery

Language code for translated labels

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Export Survey Json

GET

http://localhost:8002/api/v1/export/survey/{survey_id}/json

Quick JSON export for a survey.

Export Survey Json

curl -X GET 'http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/json'

const response = await fetch('http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/json', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/json')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

statusstring | nullquery

languagestring | nullquery

Language code for translated labels

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Export Survey Xlsx

GET

http://localhost:8002/api/v1/export/survey/{survey_id}/xlsx

Quick Excel export for a survey.

Export Survey Xlsx

curl -X GET 'http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/xlsx'

const response = await fetch('http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/xlsx', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/xlsx')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

statusstring | nullquery

languagestring | nullquery

Language code for translated labels

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Export Survey Stata

GET

http://localhost:8002/api/v1/export/survey/{survey_id}/dta

Quick STATA export for a survey.

Export Survey Stata

curl -X GET 'http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/dta'

const response = await fetch('http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/dta', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/dta')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

statusstring | nullquery

languagestring | nullquery

Language code for translated labels

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Export Survey Spss

GET

http://localhost:8002/api/v1/export/survey/{survey_id}/sav

Quick SPSS export for a survey.

Export Survey Spss

curl -X GET 'http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/sav'

const response = await fetch('http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/sav', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/export/survey/550e8400-e29b-41d4-a716-446655440000/sav')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

statusstring | nullquery

languagestring | nullquery

Language code for translated labels

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Data Service / Attachments

Attachments — Data Service

List Attachments

GET

http://localhost:8002/api/v1/attachments

List attachments with filtering.

List Attachments

curl -X GET 'http://localhost:8002/api/v1/attachments?limit=20&offset=0'

const response = await fetch('http://localhost:8002/api/v1/attachments?limit=20&offset=0', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/attachments?limit=20&offset=0')
print(response.text)

{
  "attachments": [
    {
      "id": "string",
      "entity_type": "string",
      "entity_id": "string",
      "filename": "string",
      "original_filename": "string",
      "file_type": "string",
      "mime_type": "string",
      "file_size": 0,
      "description": "string",
      "uploaded_by": "string",
      "checksum": "string",
      "is_public": true,
      "field_name": "string",
      "captured_at": "string",
      "status": "string",
      "created_at": "string",
      "download_url": "string"
    }
  ],
  "total": 0,
  "page": 0,
  "limit": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

entity_typestring | nullquery

Filter by entity type

entity_idstring | nullquery

Filter by entity ID

file_typestring | nullquery

Filter by file type (image, audio, video, document)

field_namestring | nullquery

Filter by question field name

limitinteger[1, 100]20query

offsetinteger>= 00query

Response

200OKDataService_AttachmentListDTO

Successful Response

Response fields application/json

attachmentsArray<DataService_AttachmentResponseDTO>required

Show child attributes

idstringrequired

entity_typestringrequired

entity_idstringrequired

filenamestringrequired

original_filenamestringrequired

file_typestring | nullrequired

Show child attributes

Any of

string

null

mime_typestring | nullrequired

Show child attributes

Any of

string

null

file_sizeintegerrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

uploaded_bystring | nullrequired

Show child attributes

Any of

string

null

checksumstring | nullrequired

Show child attributes

Any of

string

null

is_publicbooleanrequired

field_namestring | null

Show child attributes

Any of

string

null

captured_atstring | null

Show child attributes

Any of

string

null

statusstringrequired

created_atstringrequired

download_urlstring | null

Show child attributes

Any of

string

null

totalintegerrequired

pageintegerrequired

limitintegerrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Upload Attachment

POST

http://localhost:8002/api/v1/attachments

Upload a file attachment.

Supported file types:

Images (jpg, png, gif)
Audio (mp3, wav, ogg)
Video (mp4, avi, mov)
Documents (pdf, doc, docx, xls, xlsx)

Max file size: 50MB

Upload Attachment

curl -X POST 'http://localhost:8002/api/v1/attachments' \
  --form-string 'entity_type=string' \
  --form-string 'entity_id=550e8400-e29b-41d4-a716-446655440000' \
  --form-string 'description=string' \
  --form-string 'file=string'

const form = new FormData();
form.append('entity_type', 'string');
form.append('entity_id', '550e8400-e29b-41d4-a716-446655440000');
form.append('description', 'string');
form.append('file', 'string');
const response = await fetch('http://localhost:8002/api/v1/attachments', {
  method: 'POST',
  headers: {},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('entity_type', (None, 'string')),
        ('entity_id', (None, '550e8400-e29b-41d4-a716-446655440000')),
        ('description', (None, 'string')),
        ('file', (None, 'string')),
    ]
    response = requests.request('POST', 'http://localhost:8002/api/v1/attachments', headers={}, files=files)
    print(response.text)

Request Body

{
  "entity_type": "string",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "description": "string",
  "file": "string"
}

{
  "id": "string",
  "entity_type": "string",
  "entity_id": "string",
  "filename": "string",
  "original_filename": "string",
  "file_type": "string",
  "mime_type": "string",
  "file_size": 0,
  "description": "string",
  "uploaded_by": "string",
  "checksum": "string",
  "is_public": true,
  "field_name": "string",
  "captured_at": "string",
  "status": "string",
  "created_at": "string",
  "download_url": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

entity_typestringrequired

Entity type (response, survey, etc.)

entity_idstring<uuid>required

Entity ID

descriptionstring | null

Description

Show child attributes

Any of

string

null

filestringrequired

File to upload

Response

201CreatedDataService_AttachmentResponseDTO

Successful Response

Response fields application/json

idstringrequired

entity_typestringrequired

entity_idstringrequired

filenamestringrequired

original_filenamestringrequired

file_typestring | nullrequired

Show child attributes

Any of

string

null

mime_typestring | nullrequired

Show child attributes

Any of

string

null

file_sizeintegerrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

uploaded_bystring | nullrequired

Show child attributes

Any of

string

null

checksumstring | nullrequired

Show child attributes

Any of

string

null

is_publicbooleanrequired

field_namestring | null

Show child attributes

Any of

string

null

captured_atstring | null

Show child attributes

Any of

string

null

statusstringrequired

created_atstringrequired

download_urlstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Attachment Record

POST

http://localhost:8002/api/v1/attachments/record

Create an attachment record from provided metadata (file already uploaded via media-service).

This is used by the interview/attachment flow where the file is uploaded separately through media-service, and the data-service only stores the metadata record.

Create Attachment Record

curl -X POST 'http://localhost:8002/api/v1/attachments/record' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "entity_type": "string",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "field_name": "string",
  "filename": "string",
  "original_filename": "string",
  "file_type": "string",
  "mime_type": "string",
  "file_size": 0,
  "checksum": "string",
  "storage_url": "string",
  "captured_at": "string",
  "description": "string"
}'

const body = `{
  "entity_type": "string",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "field_name": "string",
  "filename": "string",
  "original_filename": "string",
  "file_type": "string",
  "mime_type": "string",
  "file_size": 0,
  "checksum": "string",
  "storage_url": "string",
  "captured_at": "string",
  "description": "string"
}`;

const response = await fetch('http://localhost:8002/api/v1/attachments/record', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "entity_type": "string",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "field_name": "string",
  "filename": "string",
  "original_filename": "string",
  "file_type": "string",
  "mime_type": "string",
  "file_size": 0,
  "checksum": "string",
  "storage_url": "string",
  "captured_at": "string",
  "description": "string"
}'''

response = requests.post(
    'http://localhost:8002/api/v1/attachments/record',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "entity_type": "string",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "field_name": "string",
  "filename": "string",
  "original_filename": "string",
  "file_type": "string",
  "mime_type": "string",
  "file_size": 0,
  "checksum": "string",
  "storage_url": "string",
  "captured_at": "string",
  "description": "string"
}

{
  "id": "string",
  "entity_type": "string",
  "entity_id": "string",
  "filename": "string",
  "original_filename": "string",
  "file_type": "string",
  "mime_type": "string",
  "file_size": 0,
  "description": "string",
  "uploaded_by": "string",
  "checksum": "string",
  "is_public": true,
  "field_name": "string",
  "captured_at": "string",
  "status": "string",
  "created_at": "string",
  "download_url": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

entity_typestringrequired

Type of entity (e.g., 'interview', 'response')

entity_idstring<uuid>required

ID of the associated entity

field_namestring | null

Question field name

Show child attributes

Any of

string

null

filenamestringrequired

Stored filename

original_filenamestringrequired

Original filename

file_typestring | null

File category (image, audio, video, document)

Show child attributes

Any of

string

null

mime_typestring | null

MIME type

Show child attributes

Any of

string

null

file_sizeinteger0

File size in bytes

checksumstring | null

SHA-256 checksum

Show child attributes

Any of

string

null

storage_urlstring | null

URL to the uploaded file

Show child attributes

Any of

string

null

captured_atstring | null

Device capture timestamp

Show child attributes

Any of

string

null

descriptionstring | null

Notes/description

Show child attributes

Any of

string

null

Response

201CreatedDataService_AttachmentResponseDTO

Successful Response

Response fields application/json

idstringrequired

entity_typestringrequired

entity_idstringrequired

filenamestringrequired

original_filenamestringrequired

file_typestring | nullrequired

Show child attributes

Any of

string

null

mime_typestring | nullrequired

Show child attributes

Any of

string

null

file_sizeintegerrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

uploaded_bystring | nullrequired

Show child attributes

Any of

string

null

checksumstring | nullrequired

Show child attributes

Any of

string

null

is_publicbooleanrequired

field_namestring | null

Show child attributes

Any of

string

null

captured_atstring | null

Show child attributes

Any of

string

null

statusstringrequired

created_atstringrequired

download_urlstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Attachment

GET

http://localhost:8002/api/v1/attachments/{attachment_id}

Get attachment metadata by ID.

Get Attachment

curl -X GET 'http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

{
  "id": "string",
  "entity_type": "string",
  "entity_id": "string",
  "filename": "string",
  "original_filename": "string",
  "file_type": "string",
  "mime_type": "string",
  "file_size": 0,
  "description": "string",
  "uploaded_by": "string",
  "checksum": "string",
  "is_public": true,
  "field_name": "string",
  "captured_at": "string",
  "status": "string",
  "created_at": "string",
  "download_url": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

attachment_idstring<uuid>requiredpath

Response

200OKDataService_AttachmentResponseDTO

Successful Response

Response fields application/json

idstringrequired

entity_typestringrequired

entity_idstringrequired

filenamestringrequired

original_filenamestringrequired

file_typestring | nullrequired

Show child attributes

Any of

string

null

mime_typestring | nullrequired

Show child attributes

Any of

string

null

file_sizeintegerrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

uploaded_bystring | nullrequired

Show child attributes

Any of

string

null

checksumstring | nullrequired

Show child attributes

Any of

string

null

is_publicbooleanrequired

field_namestring | null

Show child attributes

Any of

string

null

captured_atstring | null

Show child attributes

Any of

string

null

statusstringrequired

created_atstringrequired

download_urlstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Attachment

DELETE

http://localhost:8002/api/v1/attachments/{attachment_id}

Delete an attachment.

Delete Attachment

curl -X DELETE 'http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

{
  "message": "string",
  "id": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

attachment_idstring<uuid>requiredpath

Response

200OKDataService_AttachmentDeleteResponse

Successful Response

Response fields application/json

messagestringrequired

idstringrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Attachment

PATCH

http://localhost:8002/api/v1/attachments/{attachment_id}

Update attachment metadata (notes/description and field_name).

Update Attachment

curl -X PATCH 'http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "description": "string",
  "field_name": "string"
}'

const body = `{
  "description": "string",
  "field_name": "string"
}`;

const response = await fetch('http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "description": "string",
  "field_name": "string"
}'''

response = requests.patch(
    'http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "description": "string",
  "field_name": "string"
}

{
  "id": "string",
  "entity_type": "string",
  "entity_id": "string",
  "filename": "string",
  "original_filename": "string",
  "file_type": "string",
  "mime_type": "string",
  "file_size": 0,
  "description": "string",
  "uploaded_by": "string",
  "checksum": "string",
  "is_public": true,
  "field_name": "string",
  "captured_at": "string",
  "status": "string",
  "created_at": "string",
  "download_url": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

descriptionstring | null

Updated notes/description

Show child attributes

Any of

string

null

field_namestring | null

Updated question field name

Show child attributes

Any of

string

null

Parameters

attachment_idstring<uuid>requiredpath

Response

200OKDataService_AttachmentResponseDTO

Successful Response

Response fields application/json

idstringrequired

entity_typestringrequired

entity_idstringrequired

filenamestringrequired

original_filenamestringrequired

file_typestring | nullrequired

Show child attributes

Any of

string

null

mime_typestring | nullrequired

Show child attributes

Any of

string

null

file_sizeintegerrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

uploaded_bystring | nullrequired

Show child attributes

Any of

string

null

checksumstring | nullrequired

Show child attributes

Any of

string

null

is_publicbooleanrequired

field_namestring | null

Show child attributes

Any of

string

null

captured_atstring | null

Show child attributes

Any of

string

null

statusstringrequired

created_atstringrequired

download_urlstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Download Attachment

GET

http://localhost:8002/api/v1/attachments/{attachment_id}/download

Download attachment file.

Download Attachment

curl -X GET 'http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000/download'

const response = await fetch('http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000/download', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000/download')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

attachment_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Data Service / Data Analytics

Data Analytics — Data Service

Get Active Surveys

GET

http://localhost:8002/api/v1/analytics/responses/active

Get a list of all survey IDs for this tenant that have at least one response. Used by frontend to filter survey list in Data Viewer.

Get Active Surveys

curl -X GET 'http://localhost:8002/api/v1/analytics/responses/active'

const response = await fetch('http://localhost:8002/api/v1/analytics/responses/active', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/analytics/responses/active')
print(response.text)

200

[
  "string"
]

Response

200OKArray<string>

Successful Response

Response fields application/json

Array<string>

Get Response Stats

GET

http://localhost:8002/api/v1/analytics/responses/stats/{survey_id}

Get comprehensive statistics for survey responses.

Returns counts by status, completion rate, and average duration. Date-only from_date/to_date values are interpreted as local calendar days in timezone_context; full datetimes are treated as instants. The end boundary is exclusive.

Get Response Stats

curl -X GET 'http://localhost:8002/api/v1/analytics/responses/stats/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8002/api/v1/analytics/responses/stats/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/analytics/responses/stats/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

{
  "survey_id": "string",
  "total_responses": 0,
  "draft_count": 0,
  "submitted_count": 0,
  "completed_count": 0,
  "invalidated_count": 0,
  "completion_rate": 0,
  "average_duration_seconds": 0,
  "date_from": "string",
  "date_to": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

from_datestring | nullquery

Start date filter

to_datestring | nullquery

End date filter

timezone_contextstring | nullquery

IANA timezone for date-only boundaries

Response

200OKDataService_ResponseStatsDTO

Successful Response

Response fields application/json

survey_idstringrequired

total_responsesintegerrequired

draft_countintegerrequired

submitted_countintegerrequired

completed_countintegerrequired

invalidated_countintegerrequired

completion_ratenumberrequired

average_duration_secondsnumber | nullrequired

Show child attributes

Any of

number

null

date_fromstringrequired

date_tostringrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Response Timeseries

GET

http://localhost:8002/api/v1/analytics/responses/timeseries/{survey_id}

Get time-series data for survey responses.

Buckets are the effective-IANA CALENDAR day (YYYY-MM-DD), never UTC wall-clock days. timezone_context selects the zone; Postgres applies its DST rules per timestamp via created_at AT TIME ZONE :tz. Date-only from_date/to_date are interpreted as local calendar days; full datetimes are instants. The end boundary is exclusive and daily series are zero-filled so exactly the requested local calendar days are returned.

Get Response Timeseries

curl -X GET 'http://localhost:8002/api/v1/analytics/responses/timeseries/550e8400-e29b-41d4-a716-446655440000?granularity=day'

const response = await fetch('http://localhost:8002/api/v1/analytics/responses/timeseries/550e8400-e29b-41d4-a716-446655440000?granularity=day', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/analytics/responses/timeseries/550e8400-e29b-41d4-a716-446655440000?granularity=day')
print(response.text)

{
  "survey_id": "string",
  "granularity": "string",
  "data": [
    {
      "date": "string",
      "count": 0
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

granularitystringdayquery

Time granularity: day, week, month

from_datestring | nullquery

Start date

to_datestring | nullquery

End date (exclusive)

statusstring | nullquery

Filter by response status

timezone_contextstring | nullquery

IANA timezone for calendar-day bucketing

Response

200OKDataService_TimeSeriesDTO

Successful Response

Response fields application/json

survey_idstringrequired

granularitystringrequired

dataArray<DataService_TimeSeriesPointDTO>required

Show child attributes

datestringrequired

countintegerrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Question Stats

GET

http://localhost:8002/api/v1/analytics/responses/questions/{survey_id}

Get statistics for individual questions across all responses.

Shows answer counts, unique respondents, and most common values.

Get Question Stats

curl -X GET 'http://localhost:8002/api/v1/analytics/responses/questions/550e8400-e29b-41d4-a716-446655440000?limit=10'

const response = await fetch('http://localhost:8002/api/v1/analytics/responses/questions/550e8400-e29b-41d4-a716-446655440000?limit=10', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/analytics/responses/questions/550e8400-e29b-41d4-a716-446655440000?limit=10')
print(response.text)

[
  {
    "question_id": "string",
    "question_type": "string",
    "total_answers": 0,
    "unique_respondents": 0,
    "most_common_value": "string",
    "most_common_count": 0
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

limitinteger[1, 50]10query

Number of questions to return

Response

200OKArray<DataService_QuestionStatsDTO>

Successful Response

Response fields application/json

Array<DataService_QuestionStatsDTO>

Show child attributes

question_idstringrequired

question_typestringrequired

total_answersintegerrequired

unique_respondentsintegerrequired

most_common_valuestring | nullrequired

Show child attributes

Any of

string

null

most_common_countintegerrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Answer Distribution

GET

http://localhost:8002/api/v1/analytics/responses/distribution/{survey_id}/{question_id}

Get distribution of answers for a specific question.

Shows value counts and percentages - useful for multiple choice questions.

Get Answer Distribution

curl -X GET 'http://localhost:8002/api/v1/analytics/responses/distribution/550e8400-e29b-41d4-a716-446655440000/string?limit=20'

const response = await fetch('http://localhost:8002/api/v1/analytics/responses/distribution/550e8400-e29b-41d4-a716-446655440000/string?limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/analytics/responses/distribution/550e8400-e29b-41d4-a716-446655440000/string?limit=20')
print(response.text)

[
  {
    "question_id": "string",
    "value": "string",
    "count": 0,
    "percentage": 0
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

question_idstringrequiredpath

limitinteger[1, 100]20query

Response

200OKArray<DataService_AnswerDistributionDTO>

Successful Response

Response fields application/json

Array<DataService_AnswerDistributionDTO>

Show child attributes

question_idstringrequired

valuestringrequired

countintegerrequired

percentagenumberrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Analytics Summary

GET

http://localhost:8002/api/v1/analytics/responses/summary/{survey_id}

Get a comprehensive analytics summary for a survey.

Combines multiple metrics: response counts, completion rates, question statistics, and respondent information.

Get Analytics Summary

curl -X GET 'http://localhost:8002/api/v1/analytics/responses/summary/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8002/api/v1/analytics/responses/summary/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/analytics/responses/summary/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

{
  "survey_id": "string",
  "total_responses": 0,
  "unique_respondents": 0,
  "response_rate": 0,
  "average_completion_time_seconds": 0,
  "questions_analyzed": 0,
  "top_questions": [
    {
      "question_id": "string",
      "question_type": "string",
      "total_answers": 0,
      "unique_respondents": 0,
      "most_common_value": "string",
      "most_common_count": 0
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

Response

200OKDataService_AnalyticsSummaryDTO

Successful Response

Response fields application/json

survey_idstringrequired

total_responsesintegerrequired

unique_respondentsintegerrequired

response_ratenumber | nullrequired

Show child attributes

Any of

number

null

average_completion_time_secondsnumber | nullrequired

Show child attributes

Any of

number

null

questions_analyzedintegerrequired

top_questionsArray<DataService_QuestionStatsDTO>required

Show child attributes

question_idstringrequired

question_typestringrequired

total_answersintegerrequired

unique_respondentsintegerrequired

most_common_valuestring | nullrequired

Show child attributes

Any of

string

null

most_common_countintegerrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Dashboard Metrics

GET

http://localhost:8002/api/v1/analytics/dashboard

Get consolidated dashboard metrics for the Operations Center.

Returns:

active_forms: count of published surveys visible to user (0 - use survey-service)
active_enumerators: distinct users with successful submissions in last 24h
submissions_today: count of submitted/completed responses today (effective-IANA local day)
failed_submissions: count of failed push attempts today (0 - use sync-service)
latest_submission_times: per-survey latest timestamps (for "Last Submission" column)
timezone_context: timezone used for date calculations (UTC fallback)

Get Dashboard Metrics

curl -X GET 'http://localhost:8002/api/v1/analytics/dashboard'

const response = await fetch('http://localhost:8002/api/v1/analytics/dashboard', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/analytics/dashboard')
print(response.text)

{
  "active_forms": 0,
  "active_enumerators": 0,
  "submissions_today": 0,
  "failed_submissions": 0,
  "latest_submission_times": [
    {
      "survey_id": "string",
      "latest_submitted_at": "string",
      "latest_completed_at": "string"
    }
  ],
  "timezone_context": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

timezone_contextstring | nullquery

IANA timezone for calendar-day bucketing

Response

200OKDataService_DashboardMetricsDTO

Successful Response

Response fields application/json

active_formsintegerrequired

active_enumeratorsintegerrequired

submissions_todayintegerrequired

failed_submissionsintegerrequired

latest_submission_timesArray<DataService_SurveyLatestSubmissionDTO>required

Show child attributes

survey_idstringrequired

latest_submitted_atstring | nullrequired

Show child attributes

Any of

string

null

latest_completed_atstring | nullrequired

Show child attributes

Any of

string

null

timezone_contextstringrequired

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Dashboard Data

GET

http://localhost:8002/api/v1/analytics/dashboard/{survey_id}

Get all analytics data for a dashboard view.

Combines stats, timeseries, and question data in one call.

Get Dashboard Data

curl -X GET 'http://localhost:8002/api/v1/analytics/dashboard/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8002/api/v1/analytics/dashboard/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8002/api/v1/analytics/dashboard/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

timezone_contextstring | nullquery

IANA timezone for calendar-day bucketing

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Data Service / Random Sampling

Random Sampling — Data Service

Generate Random Sample

POST

http://localhost:8002/api/v1/sampling/generate

Generate a random sample from an uploaded CSV or Excel file.

file: CSV or Excel file (.csv, .xlsx, .xls)
sample_size: Number of rows to sample (must be <= total rows)
output_format: Output format: csv (default), xlsx, or json

Generate Random Sample

curl -X POST 'http://localhost:8002/api/v1/sampling/generate' \
  --form-string 'file=string' \
  --form-string 'sample_size=0' \
  --form-string 'output_format=csv'

const form = new FormData();
form.append('file', 'string');
form.append('sample_size', '0');
form.append('output_format', 'csv');
const response = await fetch('http://localhost:8002/api/v1/sampling/generate', {
  method: 'POST',
  headers: {},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('file', (None, 'string')),
        ('sample_size', (None, '0')),
        ('output_format', (None, 'csv')),
    ]
    response = requests.request('POST', 'http://localhost:8002/api/v1/sampling/generate', headers={}, files=files)
    print(response.text)

Request Body

{
  "file": "string",
  "sample_size": 0,
  "output_format": "csv"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filestringrequired

sample_sizeintegerrequired

output_formatstringcsv

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Generate Random Sample

POST

http://localhost:8002/api/v1/data/sampling/generate

Generate a random sample from an uploaded CSV or Excel file.

file: CSV or Excel file (.csv, .xlsx, .xls)
sample_size: Number of rows to sample (must be <= total rows)
output_format: Output format: csv (default), xlsx, or json

Generate Random Sample

curl -X POST 'http://localhost:8002/api/v1/data/sampling/generate' \
  --form-string 'file=string' \
  --form-string 'sample_size=0' \
  --form-string 'output_format=csv'

const form = new FormData();
form.append('file', 'string');
form.append('sample_size', '0');
form.append('output_format', 'csv');
const response = await fetch('http://localhost:8002/api/v1/data/sampling/generate', {
  method: 'POST',
  headers: {},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('file', (None, 'string')),
        ('sample_size', (None, '0')),
        ('output_format', (None, 'csv')),
    ]
    response = requests.request('POST', 'http://localhost:8002/api/v1/data/sampling/generate', headers={}, files=files)
    print(response.text)

Request Body

{
  "file": "string",
  "sample_size": 0,
  "output_format": "csv"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filestringrequired

sample_sizeintegerrequired

output_formatstringcsv

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityDataService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Sync Service

Mobile/offline sync: pull, push, devices, conflicts, reconciliation

Sync Service / Health

Health — Sync Service

Health Check

GET

http://localhost:8003/api/v1/sync/health

Health check endpoint.

Health Check

curl -X GET 'http://localhost:8003/api/v1/sync/health'

const response = await fetch('http://localhost:8003/api/v1/sync/health', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8003/api/v1/sync/health')
print(response.text)

200

{
  "status": "string",
  "service": "string",
  "version": "string",
  "timestamp": "2024-01-15T09:30:00Z",
  "database": "string"
}

Response

200OKSyncService_HealthResponseDTO

Successful Response

Response fields application/json

statusstringrequired

servicestringrequired

versionstringrequired

timestampstring<date-time>required

databasestring | null

Show child attributes

Any of

string

null

Sync Service / Devices

Devices — Sync Service

List User Devices

GET

http://localhost:8003/api/v1/sync/devices

List all devices registered for the current user.

List User Devices

curl -X GET 'http://localhost:8003/api/v1/sync/devices' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/devices', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8003/api/v1/sync/devices',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "items": [
    {
      "id": "string",
      "device_id": "string",
      "platform": "string",
      "device_name": "string",
      "device_model": "string",
      "os_version": "string",
      "app_version": "string",
      "status": "string",
      "is_primary": true,
      "last_active_at": "string",
      "created_at": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 100,
  "has_next": false,
  "has_previous": false
}

Response

200OKSyncService_DeviceListDTO

Successful Response

Response fields application/json

List of devices response.

itemsArray<SyncService_DeviceResponseDTO>required

Show child attributes

Device response.

idstringrequired

device_idstringrequired

platformstringrequired

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_primarybooleanrequired

last_active_atstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipinteger0

limitinteger100

has_nextbooleanfalse

has_previousbooleanfalse

Authorization

JWThttp (bearer)

JWT Token Authentication

Register Device

POST

http://localhost:8003/api/v1/sync/devices

One device per user per platform
If device already exists, updates registration
Sets new device as primary

curl -X POST 'http://localhost:8003/api/v1/sync/devices' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "device_id": "string",
  "platform": "string",
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "push_token": "string"
}'

const body = `{
  "device_id": "string",
  "platform": "string",
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "push_token": "string"
}`;

const response = await fetch('http://localhost:8003/api/v1/sync/devices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "device_id": "string",
  "platform": "string",
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "push_token": "string"
}'''

response = requests.post(
    'http://localhost:8003/api/v1/sync/devices',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "device_id": "string",
  "platform": "string",
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "push_token": "string"
}

{
  "id": "string",
  "device_id": "string",
  "platform": "string",
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "status": "string",
  "is_primary": true,
  "last_active_at": "string",
  "created_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Device registration request.

device_idstringrequired

Unique device identifier

platformstringrequired

Device platform (ios, android, web, desktop)

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

push_tokenstring | null

Show child attributes

Any of

string

null

Response

201CreatedSyncService_DeviceResponseDTO

Successful Response

Response fields application/json

Device response.

idstringrequired

device_idstringrequired

platformstringrequired

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_primarybooleanrequired

last_active_atstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Get Device

GET

http://localhost:8003/api/v1/sync/devices/{device_id}

Get device details by device ID.

Get Device

curl -X GET 'http://localhost:8003/api/v1/sync/devices/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/devices/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8003/api/v1/sync/devices/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "device_id": "string",
  "platform": "string",
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "status": "string",
  "is_primary": true,
  "last_active_at": "string",
  "created_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

device_idstringrequiredpath

Response

200OKSyncService_DeviceResponseDTO

Successful Response

Response fields application/json

Device response.

idstringrequired

device_idstringrequired

platformstringrequired

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_primarybooleanrequired

last_active_atstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Update Device

PUT

http://localhost:8003/api/v1/sync/devices/{device_id}

Update device information.

Update Device

curl -X PUT 'http://localhost:8003/api/v1/sync/devices/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "push_token": "string"
}'

const body = `{
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "push_token": "string"
}`;

const response = await fetch('http://localhost:8003/api/v1/sync/devices/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "push_token": "string"
}'''

response = requests.put(
    'http://localhost:8003/api/v1/sync/devices/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "push_token": "string"
}

{
  "id": "string",
  "device_id": "string",
  "platform": "string",
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "status": "string",
  "is_primary": true,
  "last_active_at": "string",
  "created_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Device update request.

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

push_tokenstring | null

Show child attributes

Any of

string

null

Parameters

device_idstringrequiredpath

Response

200OKSyncService_DeviceResponseDTO

Successful Response

Response fields application/json

Device response.

idstringrequired

device_idstringrequired

platformstringrequired

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_primarybooleanrequired

last_active_atstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Deregister Device

DELETE

http://localhost:8003/api/v1/sync/devices/{device_id}

Deregister a device.

Deregister Device

curl -X DELETE 'http://localhost:8003/api/v1/sync/devices/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/devices/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8003/api/v1/sync/devices/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

device_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Update Push Token

PATCH

http://localhost:8003/api/v1/sync/devices/{device_id}/push-token

Update device push token.

Update Push Token

curl -X PATCH 'http://localhost:8003/api/v1/sync/devices/string/push-token' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "push_token": "string"
}'

const body = `{
  "push_token": "string"
}`;

const response = await fetch('http://localhost:8003/api/v1/sync/devices/string/push-token', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "push_token": "string"
}'''

response = requests.patch(
    'http://localhost:8003/api/v1/sync/devices/string/push-token',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "push_token": "string"
}

{
  "id": "string",
  "device_id": "string",
  "platform": "string",
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "status": "string",
  "is_primary": true,
  "last_active_at": "string",
  "created_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Push token update request.

push_tokenstringrequired

Parameters

device_idstringrequiredpath

Response

200OKSyncService_DeviceResponseDTO

Successful Response

Response fields application/json

Device response.

idstringrequired

device_idstringrequired

platformstringrequired

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_primarybooleanrequired

last_active_atstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Set Primary Device

POST

http://localhost:8003/api/v1/sync/devices/{device_id}/set-primary

Set device as primary for the user.

Set Primary Device

curl -X POST 'http://localhost:8003/api/v1/sync/devices/string/set-primary' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/devices/string/set-primary', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8003/api/v1/sync/devices/string/set-primary',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "device_id": "string",
  "platform": "string",
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "status": "string",
  "is_primary": true,
  "last_active_at": "string",
  "created_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

device_idstringrequiredpath

Response

200OKSyncService_DeviceResponseDTO

Successful Response

Response fields application/json

Device response.

idstringrequired

device_idstringrequired

platformstringrequired

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_primarybooleanrequired

last_active_atstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Sync Service / Sync Pull

Sync Pull — Sync Service

Pull Sync

POST

http://localhost:8003/api/v1/sync/pull

Pull synchronized data from the server.

Delta-based: Only returns changes since last_sync_token / last checkpoint.
Surveys: Fetched from survey-service, filtered by updated_after timestamp.
Checkpoint updated: last_survey_sync_at is advanced after a successful pull.
New sync_token returned for the device to use in the next call.

Pull Sync

curl -X POST 'http://localhost:8003/api/v1/sync/pull' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "device_id": "string",
  "last_sync_token": "string",
  "survey_version": "string",
  "include_surveys": true,
  "include_metadata": true
}'

const body = `{
  "device_id": "string",
  "last_sync_token": "string",
  "survey_version": "string",
  "include_surveys": true,
  "include_metadata": true
}`;

const response = await fetch('http://localhost:8003/api/v1/sync/pull', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "device_id": "string",
  "last_sync_token": "string",
  "survey_version": "string",
  "include_surveys": true,
  "include_metadata": true
}'''

response = requests.post(
    'http://localhost:8003/api/v1/sync/pull',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "device_id": "string",
  "last_sync_token": "string",
  "survey_version": "string",
  "include_surveys": true,
  "include_metadata": true
}

{
  "sync_token": "string",
  "surveys": [
    {
      "survey_id": "string",
      "version_id": "string",
      "version": "string",
      "title": "string",
      "description": "string",
      "status": "string",
      "schema_hash": "string",
      "is_deleted": false,
      "has_lookups": false,
      "questions": [
        {}
      ],
      "settings": {}
    }
  ],
  "metadata": {
    "surveys_modified": 0,
    "surveys_deleted": 0,
    "responses_modified": 0,
    "responses_new": 0,
    "server_timestamp": "string",
    "next_sync_token": "string"
  },
  "server_timestamp": "string",
  "role": {
    "id": "string",
    "name": "string",
    "permissions": [
      "string"
    ]
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Pull sync request.

device_idstringrequired

Device identifier

last_sync_tokenstring | null

Token from previous sync

Show child attributes

Any of

string

null

survey_versionstring | null

Last known survey version (semver string)

Show child attributes

Any of

string

null

include_surveysbooleantrue

Include survey data

include_metadatabooleantrue

Include sync metadata

Response

200OKSyncService_SyncPullResponseDTO

Successful Response

Response fields application/json

Pull sync response.

sync_tokenstringrequired

surveysArray<SyncService_SurveySyncDTO>required

Show child attributes

Survey sync data — a descriptor, not a content channel (D-11).

schema_hash is the server's persisted content address for this version's canonical schema artifact: a 64-character lowercase SHA-256 over the canonical UTF-8 JSON bytes. It is forwarded verbatim from survey-service and is the value a client verifies against. It is nullable only because a legacy version published before the integrity backfill may have none; a client must treat a missing value as "cannot be verified", never as "trust me".

questions and settings remain as a legacy schema fragment. They are not a verifiable artifact (no digest covers them) and mobile ignores them; they exist so an older client does not hard-fail on a schema shape it knows. Content is fetched from the version's artifact endpoint, not from here.

survey_idstringrequired

version_idstringrequired

versionstringrequired

titlestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

schema_hashstring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

has_lookupsbooleanfalse

questionsArray<object>

settingsobject | null

Show child attributes

Any of

object

null

metadataSyncService_SyncMetadataDTOrequired

Sync metadata response.

Show child attributes

surveys_modifiedintegerrequired

surveys_deletedintegerrequired

responses_modifiedintegerrequired

responses_newintegerrequired

server_timestampstringrequired

next_sync_tokenstringrequired

server_timestampstringrequired

roleSyncService_RoleSyncDTO | null

Show child attributes

Any of

Role and permissions descriptor for sync pull response.

idstringrequired

namestringrequired

permissionsArray<string>

null

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Acknowledge Form Download

POST

http://localhost:8003/api/v1/sync/downloads/acknowledge

Record a form download after the mobile client persisted its schema.

Acknowledge Form Download

curl -X POST 'http://localhost:8003/api/v1/sync/downloads/acknowledge' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version": "string",
  "survey_title": "string",
  "schema_hash": "string",
  "device_id": "string",
  "download_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "string",
  "app_version": "string",
  "app_build": "string",
  "os_version": "string",
  "persisted_at": "2024-01-15T09:30:00Z"
}'

const body = `{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version": "string",
  "survey_title": "string",
  "schema_hash": "string",
  "device_id": "string",
  "download_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "string",
  "app_version": "string",
  "app_build": "string",
  "os_version": "string",
  "persisted_at": "2024-01-15T09:30:00Z"
}`;

const response = await fetch('http://localhost:8003/api/v1/sync/downloads/acknowledge', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version": "string",
  "survey_title": "string",
  "schema_hash": "string",
  "device_id": "string",
  "download_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "string",
  "app_version": "string",
  "app_build": "string",
  "os_version": "string",
  "persisted_at": "2024-01-15T09:30:00Z"
}'''

response = requests.post(
    'http://localhost:8003/api/v1/sync/downloads/acknowledge',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version": "string",
  "survey_title": "string",
  "schema_hash": "string",
  "device_id": "string",
  "download_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "string",
  "app_version": "string",
  "app_build": "string",
  "os_version": "string",
  "persisted_at": "2024-01-15T09:30:00Z"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Client acknowledgement emitted only after a schema is persisted locally.

survey_idstring<uuid>required

survey_version_idstring<uuid>required

survey_versionstringrequired

survey_titlestring | null

Show child attributes

Any of

string

null

schema_hashstring | null

Show child attributes

Any of

string

null

device_idstringrequired

download_idstring<uuid>required

platformstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

app_buildstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

persisted_atstring | null

Show child attributes

Any of

string<date-time>

null

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Get Sync Status

GET

http://localhost:8003/api/v1/sync/status

Get sync status for all devices of the current user.

Get Sync Status

curl -X GET 'http://localhost:8003/api/v1/sync/status' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/status', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8003/api/v1/sync/status',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

[
  {
    "device_id": "string",
    "last_sync_at": "2024-01-15T09:30:00Z",
    "sync_status": "string",
    "last_survey_sync_at": "2024-01-15T09:30:00Z",
    "last_response_sync_at": "2024-01-15T09:30:00Z",
    "sync_token": "string",
    "surveys_synced": 0,
    "responses_synced": 0,
    "server_time": "string",
    "server_time_offset": 0,
    "rid_blocks": [
      {}
    ]
  }
]

Response

200OKArray<SyncService_SyncStatusDTO>

Successful Response

Response fields application/json

Array<SyncService_SyncStatusDTO>

Show child attributes

Sync status response.

device_idstringrequired

last_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

sync_statusstringrequired

last_survey_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

last_response_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

sync_tokenstring | null

Show child attributes

Any of

string

null

surveys_syncedinteger0

responses_syncedinteger0

server_timestring | null

Show child attributes

Any of

string

null

server_time_offsetinteger | null0

Show child attributes

Any of

integer

null

rid_blocksArray<object>

Authorization

JWThttp (bearer)

JWT Token Authentication

Get Device Sync Status

GET

http://localhost:8003/api/v1/sync/status/{device_id}

Get sync status for a specific device.

Get Device Sync Status

curl -X GET 'http://localhost:8003/api/v1/sync/status/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/status/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8003/api/v1/sync/status/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "device_id": "string",
  "last_sync_at": "2024-01-15T09:30:00Z",
  "sync_status": "string",
  "last_survey_sync_at": "2024-01-15T09:30:00Z",
  "last_response_sync_at": "2024-01-15T09:30:00Z",
  "sync_token": "string",
  "surveys_synced": 0,
  "responses_synced": 0,
  "server_time": "string",
  "server_time_offset": 0,
  "rid_blocks": [
    {}
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

device_idstringrequiredpath

Response

200OKSyncService_SyncStatusDTO

Successful Response

Response fields application/json

Sync status response.

device_idstringrequired

last_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

sync_statusstringrequired

last_survey_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

last_response_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

sync_tokenstring | null

Show child attributes

Any of

string

null

surveys_syncedinteger0

responses_syncedinteger0

server_timestring | null

Show child attributes

Any of

string

null

server_time_offsetinteger | null0

Show child attributes

Any of

integer

null

rid_blocksArray<object>

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Initialize Sync

POST

http://localhost:8003/api/v1/sync/initialize

Initialize sync for a new device.

Initialize Sync

curl -X POST 'http://localhost:8003/api/v1/sync/initialize' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "device_id": "string",
  "platform": "unknown"
}'

const body = `{
  "device_id": "string",
  "platform": "unknown"
}`;

const response = await fetch('http://localhost:8003/api/v1/sync/initialize', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "device_id": "string",
  "platform": "unknown"
}'''

response = requests.post(
    'http://localhost:8003/api/v1/sync/initialize',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "device_id": "string",
  "platform": "unknown"
}

{
  "device_id": "string",
  "last_sync_at": "2024-01-15T09:30:00Z",
  "sync_status": "string",
  "last_survey_sync_at": "2024-01-15T09:30:00Z",
  "last_response_sync_at": "2024-01-15T09:30:00Z",
  "sync_token": "string",
  "surveys_synced": 0,
  "responses_synced": 0,
  "server_time": "string",
  "server_time_offset": 0,
  "rid_blocks": [
    {}
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Initial sync request.

device_idstringrequired

platformstring | nullunknown

Device platform

Show child attributes

Any of

string

null

Response

200OKSyncService_SyncStatusDTO

Successful Response

Response fields application/json

Sync status response.

device_idstringrequired

last_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

sync_statusstringrequired

last_survey_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

last_response_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

sync_tokenstring | null

Show child attributes

Any of

string

null

surveys_syncedinteger0

responses_syncedinteger0

server_timestring | null

Show child attributes

Any of

string

null

server_time_offsetinteger | null0

Show child attributes

Any of

integer

null

rid_blocksArray<object>

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Delete Device Sync

DELETE

http://localhost:8003/api/v1/sync/device/{device_id}

Delete sync record for a device.

Delete Device Sync

curl -X DELETE 'http://localhost:8003/api/v1/sync/device/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/device/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8003/api/v1/sync/device/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

device_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Sync Service / Sync Push

Sync Push — Sync Service

Push Single Response

POST

http://localhost:8003/api/v1/sync/push

Push a single survey response to the server.

Idempotent: Same idempotency_key returns same result
Persists record before forwarding to data-service
Returns push record ID for tracking

Push Single Response

curl -X POST 'http://localhost:8003/api/v1/sync/push' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "idempotency_key": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "respondent_id": "string",
  "answers": [
    {
      "question_id": "string"
    }
  ],
  "metadata": {},
  "device_id": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "response_language": "string",
  "submission_mode": "string"
}'

const body = `{
  "idempotency_key": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "respondent_id": "string",
  "answers": [
    {
      "question_id": "string"
    }
  ],
  "metadata": {},
  "device_id": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "response_language": "string",
  "submission_mode": "string"
}`;

const response = await fetch('http://localhost:8003/api/v1/sync/push', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "idempotency_key": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "respondent_id": "string",
  "answers": [
    {
      "question_id": "string"
    }
  ],
  "metadata": {},
  "device_id": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "response_language": "string",
  "submission_mode": "string"
}'''

response = requests.post(
    'http://localhost:8003/api/v1/sync/push',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "idempotency_key": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "respondent_id": "string",
  "answers": [
    {
      "question_id": "string"
    }
  ],
  "metadata": {},
  "device_id": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "response_language": "string",
  "submission_mode": "string"
}

{
  "id": "string",
  "idempotency_key": "string",
  "status": "string",
  "response_id": "string",
  "created_at": "string",
  "lifecycle_code": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Push sync request for single response.

idempotency_keystringrequired

Unique key for idempotency

survey_idstring<uuid>required

Survey ID

survey_version_idstring | null

Survey version ID for version-pinned response

Show child attributes

Any of

string<uuid>

null

interview_idstring | null

Interview execution ID — links this response to its interview lifecycle (Track A)

Show child attributes

Any of

string<uuid>

null

interview_ridstring | null

Response RID allocated for interview

Show child attributes

Any of

string

null

respondent_idstring | null

Respondent identifier

Show child attributes

Any of

string

null

answersArray<SyncService_ResponseAnswerDTO>required

Survey answers

Show child attributes

Response answer data.

question_idstringrequired

valueany

metadataobject | null

Additional metadata

Show child attributes

Any of

object

null

device_idstringrequired

Device that collected the response

collected_atstring | null

When response was collected on device

Show child attributes

Any of

string<date-time>

null

response_languagestring | null

Language code used for submission (e.g., 'en', 'es')

Show child attributes

Any of

string

null

submission_modestring | null

Submission mode: 'complete', 'terminated_partial', or 'draft'

Show child attributes

Any of

string

null

Response

202AcceptedSyncService_SyncPushResponseDTO

Successful Response

Response fields application/json

Push sync response.

idstringrequired

idempotency_keystringrequired

statusstringrequired

response_idstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

lifecycle_codestring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Push Bulk Responses

POST

http://localhost:8003/api/v1/sync/push/bulk

Push multiple survey responses in a batch.

Max 50 responses per batch
Partial success: Failed items don't block successful ones
Idempotent per item
Persists each record

Push Bulk Responses

curl -X POST 'http://localhost:8003/api/v1/sync/push/bulk' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "responses": [
    {
      "idempotency_key": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_rid": "string",
      "respondent_id": "string",
      "answers": [
        {
          "question_id": "string"
        }
      ],
      "metadata": {},
      "device_id": "string",
      "collected_at": "2024-01-15T09:30:00Z",
      "response_language": "string",
      "submission_mode": "string"
    }
  ]
}'

const body = `{
  "responses": [
    {
      "idempotency_key": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_rid": "string",
      "respondent_id": "string",
      "answers": [
        {
          "question_id": "string"
        }
      ],
      "metadata": {},
      "device_id": "string",
      "collected_at": "2024-01-15T09:30:00Z",
      "response_language": "string",
      "submission_mode": "string"
    }
  ]
}`;

const response = await fetch('http://localhost:8003/api/v1/sync/push/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "responses": [
    {
      "idempotency_key": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_rid": "string",
      "respondent_id": "string",
      "answers": [
        {
          "question_id": "string"
        }
      ],
      "metadata": {},
      "device_id": "string",
      "collected_at": "2024-01-15T09:30:00Z",
      "response_language": "string",
      "submission_mode": "string"
    }
  ]
}'''

response = requests.post(
    'http://localhost:8003/api/v1/sync/push/bulk',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "responses": [
    {
      "idempotency_key": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_rid": "string",
      "respondent_id": "string",
      "answers": [
        {
          "question_id": "string"
        }
      ],
      "metadata": {},
      "device_id": "string",
      "collected_at": "2024-01-15T09:30:00Z",
      "response_language": "string",
      "submission_mode": "string"
    }
  ]
}

{
  "total": 0,
  "accepted": 0,
  "rejected": 0,
  "results": [
    {
      "id": "string",
      "idempotency_key": "string",
      "status": "string",
      "response_id": "string",
      "created_at": "string",
      "lifecycle_code": "string"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Bulk push sync request.

responsesArray<SyncService_SyncPushRequestDTO>required

Max 50 responses per batch

Show child attributes

Push sync request for single response.

idempotency_keystringrequired

Unique key for idempotency

survey_idstring<uuid>required

Survey ID

survey_version_idstring | null

Survey version ID for version-pinned response

Show child attributes

Any of

string<uuid>

null

interview_idstring | null

Interview execution ID — links this response to its interview lifecycle (Track A)

Show child attributes

Any of

string<uuid>

null

interview_ridstring | null

Response RID allocated for interview

Show child attributes

Any of

string

null

respondent_idstring | null

Respondent identifier

Show child attributes

Any of

string

null

answersArray<SyncService_ResponseAnswerDTO>required

Survey answers

Show child attributes

Response answer data.

question_idstringrequired

valueany

metadataobject | null

Additional metadata

Show child attributes

Any of

object

null

device_idstringrequired

Device that collected the response

collected_atstring | null

When response was collected on device

Show child attributes

Any of

string<date-time>

null

response_languagestring | null

Language code used for submission (e.g., 'en', 'es')

Show child attributes

Any of

string

null

submission_modestring | null

Submission mode: 'complete', 'terminated_partial', or 'draft'

Show child attributes

Any of

string

null

Response

202AcceptedSyncService_BulkSyncPushResponseDTO

Successful Response

Response fields application/json

Bulk push sync response.

totalintegerrequired

acceptedintegerrequired

rejectedintegerrequired

resultsArray<SyncService_SyncPushResponseDTO>required

Show child attributes

Push sync response.

idstringrequired

idempotency_keystringrequired

statusstringrequired

response_idstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

lifecycle_codestring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Get Push Status

GET

http://localhost:8003/api/v1/sync/push/status/{push_id}

Get status of a push operation.

Get Push Status

curl -X GET 'http://localhost:8003/api/v1/sync/push/status/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/push/status/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8003/api/v1/sync/push/status/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "idempotency_key": "string",
  "status": "string",
  "response_id": "string",
  "created_at": "string",
  "lifecycle_code": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

push_idstringrequiredpath

Response

200OKSyncService_SyncPushResponseDTO

Successful Response

Response fields application/json

Push sync response.

idstringrequired

idempotency_keystringrequired

statusstringrequired

response_idstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

lifecycle_codestring | null

Show child attributes

Any of

string

null

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Get Pending Pushes

GET

http://localhost:8003/api/v1/sync/push/pending

Get all pending/failed push operations for retry.

Get Pending Pushes

curl -X GET 'http://localhost:8003/api/v1/sync/push/pending' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/push/pending', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8003/api/v1/sync/push/pending',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

[
  {
    "id": "string",
    "idempotency_key": "string",
    "status": "string",
    "response_id": "string",
    "created_at": "string",
    "lifecycle_code": "string"
  }
]

Response

200OKArray<SyncService_SyncPushResponseDTO>

Successful Response

Response fields application/json

Array<SyncService_SyncPushResponseDTO>

Show child attributes

Push sync response.

idstringrequired

idempotency_keystringrequired

statusstringrequired

response_idstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

lifecycle_codestring | null

Show child attributes

Any of

string

null

Authorization

JWThttp (bearer)

JWT Token Authentication

Get Failed Submissions Today

GET

http://localhost:8003/api/v1/sync/dashboard/failed-submissions

Get count of failed submission attempts today.

Counts FAILED and CONFLICT status push records created on or after the start of the effective-IANA local calendar day. timezone_context selects the zone; invalid values fall back to UTC. This provides accurate failed-submission metrics for the Operations Center dashboard.

Get Failed Submissions Today

curl -X GET 'http://localhost:8003/api/v1/sync/dashboard/failed-submissions' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/dashboard/failed-submissions', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8003/api/v1/sync/dashboard/failed-submissions',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "count": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

timezone_contextstring | nullquery

IANA timezone for the 'today' boundary

Response

200OKSyncService_FailedSubmissionsDTO

Successful Response

Response fields application/json

countintegerrequired

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Sync Service / Sync Conflicts

Sync Conflicts — Sync Service

List Unresolved Conflicts

GET

http://localhost:8003/api/v1/sync/conflicts

Get all unresolved sync conflicts for the tenant.

List Unresolved Conflicts

curl -X GET 'http://localhost:8003/api/v1/sync/conflicts' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/conflicts', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8003/api/v1/sync/conflicts',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "device_id": "string",
      "response_id": "string",
      "conflict_type": "string",
      "server_version": {},
      "client_version": {},
      "resolution": "string",
      "resolved_at": "2024-01-15T09:30:00Z",
      "resolved_by": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 100,
  "has_next": false,
  "has_previous": false
}

Response

200OKSyncService_ConflictListDTO

Successful Response

Response fields application/json

List of sync conflicts.

itemsArray<SyncService_ConflictDTO>required

Show child attributes

Sync conflict information.

idstring<uuid>required

tenant_idstring<uuid>required

device_idstringrequired

response_idstringrequired

conflict_typestringrequired

server_versionobject | null

Show child attributes

Any of

object

null

client_versionobject | null

Show child attributes

Any of

object

null

resolutionstring | null

Show child attributes

Any of

string

null

resolved_atstring | null

Show child attributes

Any of

string<date-time>

null

resolved_bystring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

totalintegerrequired

skipinteger0

limitinteger100

has_nextbooleanfalse

has_previousbooleanfalse

Authorization

JWThttp (bearer)

JWT Token Authentication

Get Conflict

GET

http://localhost:8003/api/v1/sync/conflicts/{conflict_id}

Get a specific conflict by ID.

Get Conflict

curl -X GET 'http://localhost:8003/api/v1/sync/conflicts/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/conflicts/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8003/api/v1/sync/conflicts/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "response_id": "string",
  "conflict_type": "string",
  "server_version": {},
  "client_version": {},
  "resolution": "string",
  "resolved_at": "2024-01-15T09:30:00Z",
  "resolved_by": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

conflict_idstringrequiredpath

Response

200OKSyncService_ConflictDTO

Successful Response

Response fields application/json

Sync conflict information.

idstring<uuid>required

tenant_idstring<uuid>required

device_idstringrequired

response_idstringrequired

conflict_typestringrequired

server_versionobject | null

Show child attributes

Any of

object

null

client_versionobject | null

Show child attributes

Any of

object

null

resolutionstring | null

Show child attributes

Any of

string

null

resolved_atstring | null

Show child attributes

Any of

string<date-time>

null

resolved_bystring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Resolve Conflict

POST

http://localhost:8003/api/v1/sync/conflicts/{conflict_id}/resolve

Resolve a sync conflict using a specified strategy (server_wins, client_wins).

Resolve Conflict

curl -X POST 'http://localhost:8003/api/v1/sync/conflicts/string/resolve' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "strategy": "string",
  "merged_data": {}
}'

const body = `{
  "strategy": "string",
  "merged_data": {}
}`;

const response = await fetch('http://localhost:8003/api/v1/sync/conflicts/string/resolve', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "strategy": "string",
  "merged_data": {}
}'''

response = requests.post(
    'http://localhost:8003/api/v1/sync/conflicts/string/resolve',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "strategy": "string",
  "merged_data": {}
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to resolve a sync conflict.

strategystringrequired

Resolution strategy: server_wins, client_wins, or manual

merged_dataobject | null

Merged data if manual strategy is used

Show child attributes

Any of

object

null

Parameters

conflict_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Sync Service / Sync Response Changes

Sync Response Changes — Sync Service

List Response Changes

GET

http://localhost:8003/api/v1/sync/responses/changes

Discover response status/answer-schema changes since a client-held cursor.

List Response Changes

curl -X GET 'http://localhost:8003/api/v1/sync/responses/changes?since=0&limit=100' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/responses/changes?since=0&limit=100', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8003/api/v1/sync/responses/changes?since=0&limit=100',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

sincestring0query

Watermark returned by a previous page; held and resent by the client

limitinteger[1, 1000]100query

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Correct Response

POST

http://localhost:8003/api/v1/sync/responses/{response_id}/correct

Resubmit a corrected (previously rejected) response against its existing ID.

Correct Response

curl -X POST 'http://localhost:8003/api/v1/sync/responses/550e8400-e29b-41d4-a716-446655440000/correct' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8003/api/v1/sync/responses/550e8400-e29b-41d4-a716-446655440000/correct', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8003/api/v1/sync/responses/550e8400-e29b-41d4-a716-446655440000/correct',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

response_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Sync Service / Sync Reconciliation

Sync Reconciliation — Sync Service

Reconcile Revoked Work

POST

http://localhost:8003/api/v1/sync/reconcile

Server-Authorized Reconciliation Endpoint (R17 & R22).

Validates that responses collected prior to access revocation are legitimate and eligible for governed ingestion. Rejects responses collected after revocation or collected without assignment with HTTP 403 Forbidden.

Reconcile Revoked Work

curl -X POST 'http://localhost:8003/api/v1/sync/reconcile' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "intent": "string",
  "idempotency_key": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "answers": [
    {
      "question_id": "string"
    }
  ],
  "respondent_id": "string",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "metadata": {},
  "response_language": "string",
  "submission_mode": "complete",
  "duration_seconds": 0,
  "sync_batch_id": "550e8400-e29b-41d4-a716-446655440000"
}'

const body = `{
  "intent": "string",
  "idempotency_key": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "answers": [
    {
      "question_id": "string"
    }
  ],
  "respondent_id": "string",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "metadata": {},
  "response_language": "string",
  "submission_mode": "complete",
  "duration_seconds": 0,
  "sync_batch_id": "550e8400-e29b-41d4-a716-446655440000"
}`;

const response = await fetch('http://localhost:8003/api/v1/sync/reconcile', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "intent": "string",
  "idempotency_key": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "answers": [
    {
      "question_id": "string"
    }
  ],
  "respondent_id": "string",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "metadata": {},
  "response_language": "string",
  "submission_mode": "complete",
  "duration_seconds": 0,
  "sync_batch_id": "550e8400-e29b-41d4-a716-446655440000"
}'''

response = requests.post(
    'http://localhost:8003/api/v1/sync/reconcile',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "intent": "string",
  "idempotency_key": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "answers": [
    {
      "question_id": "string"
    }
  ],
  "respondent_id": "string",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "metadata": {},
  "response_language": "string",
  "submission_mode": "complete",
  "duration_seconds": 0,
  "sync_batch_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "status": "string",
  "response_id": "string",
  "reconciliation_grant_id": "string",
  "reconciled_at": "string",
  "reason": "string",
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Server-authorized reconciliation request for responses predating access revocation (R17 & R22).

intentstringrequired

Explicit intent: must be 'reconcile_revoked_work'

idempotency_keystringrequired

Unique key for idempotency

survey_idstring<uuid>required

Survey ID

survey_version_idstring | null

Survey version ID for version pinning

Show child attributes

Any of

string<uuid>

null

device_idstringrequired

Device that collected the response

collected_atstring<date-time>required

Device-reported capture timestamp (mandatory for reconciliation)

answersArray<SyncService_ResponseAnswerDTO>required

Survey answers

Show child attributes

Response answer data.

question_idstringrequired

valueany

respondent_idstring | null

Respondent identifier

Show child attributes

Any of

string

null

interview_idstring | null

Interview execution ID

Show child attributes

Any of

string<uuid>

null

interview_ridstring | null

Allocated RID

Show child attributes

Any of

string

null

metadataobject | null

Additional metadata

Show child attributes

Any of

object

null

response_languagestring | null

Language code

Show child attributes

Any of

string

null

submission_modestring | nullcomplete

Submission mode: 'complete' or 'terminated_partial'

Show child attributes

Any of

string

null

duration_secondsinteger | null

Duration in seconds

Show child attributes

Any of

integer>= 0

null

sync_batch_idstring | null

Batch ID

Show child attributes

Any of

string<uuid>

null

Response

200OKSyncService_SyncReconciliationResponseDTO

Successful Response

Response fields application/json

Server-authorized reconciliation response.

statusstringrequired

'reconciled', 'duplicate', or 'rejected'

response_idstring | null

Persisted SurveyResponse ID in data-service

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Historical grant UUID that authorized this work

Show child attributes

Any of

string

null

reconciled_atstring | null

ISO timestamp when reconciliation completed

Show child attributes

Any of

string

null

reasonstring | null

Reason code if rejected (e.g. 'work_postdates_revocation', 'user_never_assigned')

Show child attributes

Any of

string

null

messagestringrequired

Human-readable status summary

422Unprocessable EntitySyncService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

JWThttp (bearer)

JWT Token Authentication

Analytics Service

Dashboards, widgets, aggregate analytics over response data

Analytics Service / Health

Health — Analytics Service

Analytics Service / Dashboards

Dashboards — Analytics Service

Get Dashboard Summary

GET

http://localhost:8004/api/v1/analytics/custom-dashboards/summary

Get dashboard summary metrics for the tenant.

Cached for 5 minutes. Tenant-scoped.

Get Dashboard Summary

curl -X GET 'http://localhost:8004/api/v1/analytics/custom-dashboards/summary?period=7d'

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/summary?period=7d', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8004/api/v1/analytics/custom-dashboards/summary?period=7d')
print(response.text)

{
  "tenant_id": "string",
  "period_start": "2024-01-15T09:30:00Z",
  "period_end": "2024-01-15T09:30:00Z",
  "total_surveys": 0,
  "active_surveys": 0,
  "total_responses": 0,
  "completion_rate_avg": 0,
  "average_response_time": 0,
  "responses_trend": [
    {}
  ],
  "top_surveys": [
    {}
  ],
  "generated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

periodstring7dquery

Response

200OKAnalyticsService_DashboardSummaryDTO

Successful Response

Response fields application/json

Dashboard summary metrics.

tenant_idstringrequired

period_startstring<date-time>required

period_endstring<date-time>required

total_surveysintegerrequired

active_surveysintegerrequired

total_responsesintegerrequired

completion_rate_avgnumberrequired

average_response_timenumber | nullrequired

Show child attributes

Any of

number

null

responses_trendArray<object>required

top_surveysArray<object>required

generated_atstring<date-time>required

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Survey Performance

GET

http://localhost:8004/api/v1/analytics/custom-dashboards/surveys/performance

Get survey performance metrics.

Cached for 5 minutes. Tenant-scoped.

Get Survey Performance

curl -X GET 'http://localhost:8004/api/v1/analytics/custom-dashboards/surveys/performance?limit=10&period=7d'

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/surveys/performance?limit=10&period=7d', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8004/api/v1/analytics/custom-dashboards/surveys/performance?limit=10&period=7d')
print(response.text)

[
  {
    "survey_id": "string",
    "survey_name": "string",
    "total_responses": 0,
    "completion_rate": 0,
    "average_time_seconds": 0,
    "trend": "string",
    "trend_percentage": 0
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

limitinteger[1, 100]10query

periodstring7dquery

Response

200OKArray<AnalyticsService_SurveyPerformanceDTO>

Successful Response

Response fields application/json

Array<AnalyticsService_SurveyPerformanceDTO>

Show child attributes

Survey performance metrics.

survey_idstringrequired

survey_namestringrequired

total_responsesintegerrequired

completion_ratenumberrequired

average_time_secondsnumber | nullrequired

Show child attributes

Any of

number

null

trendstringrequired

trend_percentagenumberrequired

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Response Metrics

GET

http://localhost:8004/api/v1/analytics/custom-dashboards/responses/metrics

Get response metrics over time.

Cached for 5 minutes. Tenant-scoped.

Get Response Metrics

curl -X GET 'http://localhost:8004/api/v1/analytics/custom-dashboards/responses/metrics?period=7d'

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/responses/metrics?period=7d', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8004/api/v1/analytics/custom-dashboards/responses/metrics?period=7d')
print(response.text)

[
  {
    "date": "string",
    "total_responses": 0,
    "completed_responses": 0,
    "completion_rate": 0,
    "average_duration_seconds": 0
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

periodstring7dquery

Response

200OKArray<AnalyticsService_ResponseMetricsDTO>

Successful Response

Response fields application/json

Array<AnalyticsService_ResponseMetricsDTO>

Show child attributes

Response metrics for a date range.

datestringrequired

total_responsesintegerrequired

completed_responsesintegerrequired

completion_ratenumberrequired

average_duration_secondsnumber | nullrequired

Show child attributes

Any of

number

null

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Invalidate Dashboard Cache

POST

http://localhost:8004/api/v1/analytics/custom-dashboards/invalidate-cache

Invalidate all dashboard cache for the tenant.

Useful after significant data changes.

Invalidate Dashboard Cache

curl -X POST 'http://localhost:8004/api/v1/analytics/custom-dashboards/invalidate-cache'

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/invalidate-cache', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8004/api/v1/analytics/custom-dashboards/invalidate-cache')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

List Dashboards

GET

http://localhost:8004/api/v1/analytics/custom-dashboards

List all dashboards for the tenant.

List Dashboards

curl -X GET 'http://localhost:8004/api/v1/analytics/custom-dashboards?skip=0&limit=20'

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8004/api/v1/analytics/custom-dashboards?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "is_default": true,
      "layout_config": {},
      "created_by": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "widgets": [
        {
          "id": "string",
          "dashboard_id": "string",
          "widget_type": "string",
          "title": "string",
          "title_key": "string",
          "chart_type": "string",
          "data_source": "string",
          "query_config": {},
          "position_x": 0,
          "position_y": 0,
          "width": 0,
          "height": 0,
          "config": {},
          "filters": {},
          "refresh_interval": 0,
          "created_at": "2024-01-15T09:30:00Z",
          "updated_at": "2024-01-15T09:30:00Z"
        }
      ],
      "survey_id": "string",
      "dashboard_type": "string",
      "is_user_modified": true,
      "generated_by_system": true,
      "source_survey_version": "string",
      "generator_version": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

Response

200OKAnalyticsService_DashboardListDTO

Successful Response

Response fields application/json

itemsArray<AnalyticsService_DashboardResponseDTO>required

Show child attributes

Dashboard response.

idstringrequired

titlestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_defaultbooleanrequired

layout_configobject | nullrequired

Show child attributes

Any of

object

null

created_bystringrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

widgetsArray<AnalyticsService_WidgetResponseDTO> | null

Show child attributes

Any of

Array<AnalyticsService_WidgetResponseDTO>

Show child attributes

Widget response.

idstringrequired

dashboard_idstringrequired

widget_typestringrequired

titlestringrequired

title_keystring | null

Show child attributes

Any of

string

null

chart_typestring | nullrequired

Show child attributes

Any of

string

null

data_sourcestring | nullrequired

Show child attributes

Any of

string

null

query_configobject | nullrequired

Show child attributes

Any of

object

null

position_xintegerrequired

position_yintegerrequired

widthintegerrequired

heightintegerrequired

configobject | nullrequired

Show child attributes

Any of

object

null

filtersobject | nullrequired

Show child attributes

Any of

object

null

refresh_intervalintegerrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

survey_idstring | null

Show child attributes

Any of

string

null

dashboard_typestring | null

Show child attributes

Any of

string

null

is_user_modifiedboolean | null

Show child attributes

Any of

boolean

null

generated_by_systemboolean | null

Show child attributes

Any of

boolean

null

source_survey_versionstring | null

Show child attributes

Any of

string

null

generator_versionstring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Dashboard

POST

http://localhost:8004/api/v1/analytics/custom-dashboards

Create a new dashboard.

Create Dashboard

curl -X POST 'http://localhost:8004/api/v1/analytics/custom-dashboards' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "title": "string",
  "description": "string",
  "is_default": false,
  "survey_id": "string",
  "dashboard_type": "string",
  "layout_config": {}
}'

const body = `{
  "title": "string",
  "description": "string",
  "is_default": false,
  "survey_id": "string",
  "dashboard_type": "string",
  "layout_config": {}
}`;

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "title": "string",
  "description": "string",
  "is_default": false,
  "survey_id": "string",
  "dashboard_type": "string",
  "layout_config": {}
}'''

response = requests.post(
    'http://localhost:8004/api/v1/analytics/custom-dashboards',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "title": "string",
  "description": "string",
  "is_default": false,
  "survey_id": "string",
  "dashboard_type": "string",
  "layout_config": {}
}

{
  "id": "string",
  "title": "string",
  "description": "string",
  "is_default": true,
  "layout_config": {},
  "created_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "widgets": [
    {
      "id": "string",
      "dashboard_id": "string",
      "widget_type": "string",
      "title": "string",
      "title_key": "string",
      "chart_type": "string",
      "data_source": "string",
      "query_config": {},
      "position_x": 0,
      "position_y": 0,
      "width": 0,
      "height": 0,
      "config": {},
      "filters": {},
      "refresh_interval": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "survey_id": "string",
  "dashboard_type": "string",
  "is_user_modified": true,
  "generated_by_system": true,
  "source_survey_version": "string",
  "generator_version": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Create dashboard request.

titlestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

is_defaultbooleanfalse

survey_idstring | null

Show child attributes

Any of

string

null

dashboard_typestring | null

Show child attributes

Any of

string

null

layout_configobject | null

Show child attributes

Any of

object

null

Response

201CreatedAnalyticsService_DashboardResponseDTO

Successful Response

Response fields application/json

Dashboard response.

idstringrequired

titlestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_defaultbooleanrequired

layout_configobject | nullrequired

Show child attributes

Any of

object

null

created_bystringrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

widgetsArray<AnalyticsService_WidgetResponseDTO> | null

Show child attributes

Any of

Array<AnalyticsService_WidgetResponseDTO>

Show child attributes

Widget response.

idstringrequired

dashboard_idstringrequired

widget_typestringrequired

titlestringrequired

title_keystring | null

Show child attributes

Any of

string

null

chart_typestring | nullrequired

Show child attributes

Any of

string

null

data_sourcestring | nullrequired

Show child attributes

Any of

string

null

query_configobject | nullrequired

Show child attributes

Any of

object

null

position_xintegerrequired

position_yintegerrequired

widthintegerrequired

heightintegerrequired

configobject | nullrequired

Show child attributes

Any of

object

null

filtersobject | nullrequired

Show child attributes

Any of

object

null

refresh_intervalintegerrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

survey_idstring | null

Show child attributes

Any of

string

null

dashboard_typestring | null

Show child attributes

Any of

string

null

is_user_modifiedboolean | null

Show child attributes

Any of

boolean

null

generated_by_systemboolean | null

Show child attributes

Any of

boolean

null

source_survey_versionstring | null

Show child attributes

Any of

string

null

generator_versionstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Dashboard

GET

http://localhost:8004/api/v1/analytics/custom-dashboards/{dashboard_id}

Get a dashboard by ID with its widgets.

Get Dashboard

curl -X GET 'http://localhost:8004/api/v1/analytics/custom-dashboards/string'

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8004/api/v1/analytics/custom-dashboards/string')
print(response.text)

{
  "id": "string",
  "title": "string",
  "description": "string",
  "is_default": true,
  "layout_config": {},
  "created_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "widgets": [
    {
      "id": "string",
      "dashboard_id": "string",
      "widget_type": "string",
      "title": "string",
      "title_key": "string",
      "chart_type": "string",
      "data_source": "string",
      "query_config": {},
      "position_x": 0,
      "position_y": 0,
      "width": 0,
      "height": 0,
      "config": {},
      "filters": {},
      "refresh_interval": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "survey_id": "string",
  "dashboard_type": "string",
  "is_user_modified": true,
  "generated_by_system": true,
  "source_survey_version": "string",
  "generator_version": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

dashboard_idstringrequiredpath

Response

200OKAnalyticsService_DashboardResponseDTO

Successful Response

Response fields application/json

Dashboard response.

idstringrequired

titlestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_defaultbooleanrequired

layout_configobject | nullrequired

Show child attributes

Any of

object

null

created_bystringrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

widgetsArray<AnalyticsService_WidgetResponseDTO> | null

Show child attributes

Any of

Array<AnalyticsService_WidgetResponseDTO>

Show child attributes

Widget response.

idstringrequired

dashboard_idstringrequired

widget_typestringrequired

titlestringrequired

title_keystring | null

Show child attributes

Any of

string

null

chart_typestring | nullrequired

Show child attributes

Any of

string

null

data_sourcestring | nullrequired

Show child attributes

Any of

string

null

query_configobject | nullrequired

Show child attributes

Any of

object

null

position_xintegerrequired

position_yintegerrequired

widthintegerrequired

heightintegerrequired

configobject | nullrequired

Show child attributes

Any of

object

null

filtersobject | nullrequired

Show child attributes

Any of

object

null

refresh_intervalintegerrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

survey_idstring | null

Show child attributes

Any of

string

null

dashboard_typestring | null

Show child attributes

Any of

string

null

is_user_modifiedboolean | null

Show child attributes

Any of

boolean

null

generated_by_systemboolean | null

Show child attributes

Any of

boolean

null

source_survey_versionstring | null

Show child attributes

Any of

string

null

generator_versionstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Dashboard

PUT

http://localhost:8004/api/v1/analytics/custom-dashboards/{dashboard_id}

Update a dashboard.

Update Dashboard

curl -X PUT 'http://localhost:8004/api/v1/analytics/custom-dashboards/string' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "title": "string",
  "description": "string",
  "is_default": true,
  "layout_config": {},
  "is_user_modified": true
}'

const body = `{
  "title": "string",
  "description": "string",
  "is_default": true,
  "layout_config": {},
  "is_user_modified": true
}`;

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/string', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "title": "string",
  "description": "string",
  "is_default": true,
  "layout_config": {},
  "is_user_modified": true
}'''

response = requests.put(
    'http://localhost:8004/api/v1/analytics/custom-dashboards/string',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "title": "string",
  "description": "string",
  "is_default": true,
  "layout_config": {},
  "is_user_modified": true
}

{
  "id": "string",
  "title": "string",
  "description": "string",
  "is_default": true,
  "layout_config": {},
  "created_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "widgets": [
    {
      "id": "string",
      "dashboard_id": "string",
      "widget_type": "string",
      "title": "string",
      "title_key": "string",
      "chart_type": "string",
      "data_source": "string",
      "query_config": {},
      "position_x": 0,
      "position_y": 0,
      "width": 0,
      "height": 0,
      "config": {},
      "filters": {},
      "refresh_interval": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "survey_id": "string",
  "dashboard_type": "string",
  "is_user_modified": true,
  "generated_by_system": true,
  "source_survey_version": "string",
  "generator_version": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Update dashboard request.

titlestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

is_defaultboolean | null

Show child attributes

Any of

boolean

null

layout_configobject | null

Show child attributes

Any of

object

null

is_user_modifiedboolean | null

Show child attributes

Any of

boolean

null

Parameters

dashboard_idstringrequiredpath

Response

200OKAnalyticsService_DashboardResponseDTO

Successful Response

Response fields application/json

Dashboard response.

idstringrequired

titlestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_defaultbooleanrequired

layout_configobject | nullrequired

Show child attributes

Any of

object

null

created_bystringrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

widgetsArray<AnalyticsService_WidgetResponseDTO> | null

Show child attributes

Any of

Array<AnalyticsService_WidgetResponseDTO>

Show child attributes

Widget response.

idstringrequired

dashboard_idstringrequired

widget_typestringrequired

titlestringrequired

title_keystring | null

Show child attributes

Any of

string

null

chart_typestring | nullrequired

Show child attributes

Any of

string

null

data_sourcestring | nullrequired

Show child attributes

Any of

string

null

query_configobject | nullrequired

Show child attributes

Any of

object

null

position_xintegerrequired

position_yintegerrequired

widthintegerrequired

heightintegerrequired

configobject | nullrequired

Show child attributes

Any of

object

null

filtersobject | nullrequired

Show child attributes

Any of

object

null

refresh_intervalintegerrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

survey_idstring | null

Show child attributes

Any of

string

null

dashboard_typestring | null

Show child attributes

Any of

string

null

is_user_modifiedboolean | null

Show child attributes

Any of

boolean

null

generated_by_systemboolean | null

Show child attributes

Any of

boolean

null

source_survey_versionstring | null

Show child attributes

Any of

string

null

generator_versionstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Dashboard

DELETE

http://localhost:8004/api/v1/analytics/custom-dashboards/{dashboard_id}

Delete a dashboard and all its widgets.

Delete Dashboard

curl -X DELETE 'http://localhost:8004/api/v1/analytics/custom-dashboards/string'

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/string', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8004/api/v1/analytics/custom-dashboards/string')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

dashboard_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Widget

POST

http://localhost:8004/api/v1/analytics/custom-dashboards/{dashboard_id}/widgets

Add a widget to a dashboard.

Create Widget

curl -X POST 'http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "widget_type": "string",
  "title": "string",
  "chart_type": "string",
  "data_source": "snapshot",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 4,
  "height": 3,
  "config": {},
  "filters": {},
  "refresh_interval": 300
}'

const body = `{
  "widget_type": "string",
  "title": "string",
  "chart_type": "string",
  "data_source": "snapshot",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 4,
  "height": 3,
  "config": {},
  "filters": {},
  "refresh_interval": 300
}`;

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "widget_type": "string",
  "title": "string",
  "chart_type": "string",
  "data_source": "snapshot",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 4,
  "height": 3,
  "config": {},
  "filters": {},
  "refresh_interval": 300
}'''

response = requests.post(
    'http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "widget_type": "string",
  "title": "string",
  "chart_type": "string",
  "data_source": "snapshot",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 4,
  "height": 3,
  "config": {},
  "filters": {},
  "refresh_interval": 300
}

{
  "id": "string",
  "dashboard_id": "string",
  "widget_type": "string",
  "title": "string",
  "title_key": "string",
  "chart_type": "string",
  "data_source": "string",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 0,
  "height": 0,
  "config": {},
  "filters": {},
  "refresh_interval": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Create widget request.

widget_typestringrequired

titlestringrequired

chart_typestringrequired

data_sourcestringsnapshot

query_configobject | null

Show child attributes

Any of

object

null

position_xinteger0

position_yinteger0

widthinteger4

heightinteger3

configobject | null

Show child attributes

Any of

object

null

filtersobject | null

Show child attributes

Any of

object

null

refresh_intervalinteger300

Parameters

dashboard_idstringrequiredpath

Response

201CreatedAnalyticsService_WidgetResponseDTO

Successful Response

Response fields application/json

Widget response.

idstringrequired

dashboard_idstringrequired

widget_typestringrequired

titlestringrequired

title_keystring | null

Show child attributes

Any of

string

null

chart_typestring | nullrequired

Show child attributes

Any of

string

null

data_sourcestring | nullrequired

Show child attributes

Any of

string

null

query_configobject | nullrequired

Show child attributes

Any of

object

null

position_xintegerrequired

position_yintegerrequired

widthintegerrequired

heightintegerrequired

configobject | nullrequired

Show child attributes

Any of

object

null

filtersobject | nullrequired

Show child attributes

Any of

object

null

refresh_intervalintegerrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Widget

PUT

http://localhost:8004/api/v1/analytics/custom-dashboards/{dashboard_id}/widgets/{widget_id}

Update a widget.

Update Widget

curl -X PUT 'http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets/string' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "title": "string",
  "chart_type": "string",
  "data_source": "string",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 0,
  "height": 0,
  "config": {},
  "filters": {},
  "refresh_interval": 0
}'

const body = `{
  "title": "string",
  "chart_type": "string",
  "data_source": "string",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 0,
  "height": 0,
  "config": {},
  "filters": {},
  "refresh_interval": 0
}`;

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets/string', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "title": "string",
  "chart_type": "string",
  "data_source": "string",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 0,
  "height": 0,
  "config": {},
  "filters": {},
  "refresh_interval": 0
}'''

response = requests.put(
    'http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets/string',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "title": "string",
  "chart_type": "string",
  "data_source": "string",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 0,
  "height": 0,
  "config": {},
  "filters": {},
  "refresh_interval": 0
}

{
  "id": "string",
  "dashboard_id": "string",
  "widget_type": "string",
  "title": "string",
  "title_key": "string",
  "chart_type": "string",
  "data_source": "string",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 0,
  "height": 0,
  "config": {},
  "filters": {},
  "refresh_interval": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Update widget request.

titlestring | null

Show child attributes

Any of

string

null

chart_typestring | null

Show child attributes

Any of

string

null

data_sourcestring | null

Show child attributes

Any of

string

null

query_configobject | null

Show child attributes

Any of

object

null

position_xinteger | null

Show child attributes

Any of

integer

null

position_yinteger | null

Show child attributes

Any of

integer

null

widthinteger | null

Show child attributes

Any of

integer

null

heightinteger | null

Show child attributes

Any of

integer

null

configobject | null

Show child attributes

Any of

object

null

filtersobject | null

Show child attributes

Any of

object

null

refresh_intervalinteger | null

Show child attributes

Any of

integer

null

Response

200OKAnalyticsService_WidgetResponseDTO

Successful Response

Response fields application/json

Widget response.

idstringrequired

dashboard_idstringrequired

widget_typestringrequired

titlestringrequired

title_keystring | null

Show child attributes

Any of

string

null

chart_typestring | nullrequired

Show child attributes

Any of

string

null

data_sourcestring | nullrequired

Show child attributes

Any of

string

null

query_configobject | nullrequired

Show child attributes

Any of

object

null

position_xintegerrequired

position_yintegerrequired

widthintegerrequired

heightintegerrequired

configobject | nullrequired

Show child attributes

Any of

object

null

filtersobject | nullrequired

Show child attributes

Any of

object

null

refresh_intervalintegerrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

Delete Widget

DELETE

http://localhost:8004/api/v1/analytics/custom-dashboards/{dashboard_id}/widgets/{widget_id}

Delete a widget.

Delete Widget

curl -X DELETE 'http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets/string'

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets/string', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets/string')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Get Widget Data

GET

http://localhost:8004/api/v1/analytics/custom-dashboards/{dashboard_id}/widgets/{widget_id}/data

Get data for a widget.

Routes to appropriate data source:

snapshot: Query local analytics_snapshots table
realtime: Proxy to data-service for live data

Get Widget Data

curl -X GET 'http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets/string/data'

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets/string/data', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8004/api/v1/analytics/custom-dashboards/string/widgets/string/data')
print(response.text)

{
  "widget_id": "string",
  "data_source": "string",
  "cached": false,
  "generated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Response

Generate Default Dashboard

POST

http://localhost:8004/api/v1/analytics/custom-dashboards/generate

Generate or regenerate a default dashboard for a published survey.

The generator decides whether to create, skip, or regenerate based on dashboard state and survey version. No force parameter needed.

Generate Default Dashboard

curl -X POST 'http://localhost:8004/api/v1/analytics/custom-dashboards/generate' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "string"
}'

const body = `{
  "survey_id": "string"
}`;

const response = await fetch('http://localhost:8004/api/v1/analytics/custom-dashboards/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "string"
}'''

response = requests.post(
    'http://localhost:8004/api/v1/analytics/custom-dashboards/generate',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "string"
}

{
  "dashboard_id": "string",
  "status": "string",
  "widget_count": 0,
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to generate a default dashboard for a survey.

survey_idstringrequired

Response

200OKAnalyticsService_GenerateDashboardResponseDTO

Successful Response

Response fields application/json

Response from dashboard generation.

dashboard_idstringrequired

statusstringrequired

widget_countintegerrequired

messagestringrequired

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Analytics Service / Analytics

Analytics — Analytics Service

Get Survey Analytics

GET

http://localhost:8004/api/v1/analytics/surveys/{survey_id}

Get analytics for a specific survey.

Get Survey Analytics

curl -X GET 'http://localhost:8004/api/v1/analytics/surveys/string'

const response = await fetch('http://localhost:8004/api/v1/analytics/surveys/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8004/api/v1/analytics/surveys/string')
print(response.text)

{
  "survey_id": "string",
  "total_responses": 0,
  "completion_rate": 0,
  "average_time": 0,
  "questions_count": 0,
  "responses_by_date": [
    {}
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstringrequiredpath

start_datestring | nullquery

end_datestring | nullquery

Response

200OKAnalyticsService_SurveyAnalyticsDTO

Successful Response

Response fields application/json

Survey analytics.

survey_idstringrequired

total_responsesintegerrequired

completion_ratenumberrequired

average_timenumber | nullrequired

Show child attributes

Any of

number

null

questions_countintegerrequired

responses_by_dateArray<object>required

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Analytics Summary

GET

http://localhost:8004/api/v1/analytics/summary

Get overall analytics summary for the tenant.

Get Analytics Summary

curl -X GET 'http://localhost:8004/api/v1/analytics/summary'

const response = await fetch('http://localhost:8004/api/v1/analytics/summary', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8004/api/v1/analytics/summary')
print(response.text)

{
  "total_surveys": 0,
  "total_responses": 0,
  "active_surveys": 0,
  "completion_rate_avg": 0,
  "period_start": "2024-01-15T09:30:00Z",
  "period_end": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

start_datestring | nullquery

Start date for the period

end_datestring | nullquery

End date for the period

Response

200OKAnalyticsService_AnalyticsSummaryDTO

Successful Response

Response fields application/json

Analytics summary.

total_surveysintegerrequired

total_responsesintegerrequired

active_surveysintegerrequired

completion_rate_avgnumberrequired

period_startstring<date-time>required

period_endstring<date-time>required

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Survey Responses

GET

http://localhost:8004/api/v1/analytics/surveys/{survey_id}/responses

Get paginated responses for a survey.

Get Survey Responses

curl -X GET 'http://localhost:8004/api/v1/analytics/surveys/string/responses?skip=0&limit=100'

const response = await fetch('http://localhost:8004/api/v1/analytics/surveys/string/responses?skip=0&limit=100', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8004/api/v1/analytics/surveys/string/responses?skip=0&limit=100')
print(response.text)

{
  "items": [
    {}
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstringrequiredpath

skipinteger>= 00query

limitinteger[1, 1000]100query

Response

200OKAnalyticsService_AnalyticsResponseListDTO

Successful Response

Response fields application/json

Paginated list of survey responses for analytics.

itemsArray<object>required

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Survey Questions Analytics

GET

http://localhost:8004/api/v1/analytics/surveys/{survey_id}/questions

Get analytics per question for a survey.

Get Survey Questions Analytics

curl -X GET 'http://localhost:8004/api/v1/analytics/surveys/string/questions'

const response = await fetch('http://localhost:8004/api/v1/analytics/surveys/string/questions', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8004/api/v1/analytics/surveys/string/questions')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Export Survey Analytics

GET

http://localhost:8004/api/v1/analytics/export/{survey_id}

Export survey analytics in the specified format.

Export Survey Analytics

curl -X GET 'http://localhost:8004/api/v1/analytics/export/string?format=json'

const response = await fetch('http://localhost:8004/api/v1/analytics/export/string?format=json', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8004/api/v1/analytics/export/string?format=json')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstringrequiredpath

formatstringjsonquery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Aggregate Survey Data

POST

http://localhost:8004/api/v1/analytics/aggregate

Aggregate survey response data for chart visualisation.

Fetches raw responses from data-service, computes aggregation locally, and caches the result in Redis for 5 minutes.

Aggregation types:

count / distribution → frequency per unique value
average → numeric histogram with min/max/avg summary
sum → single total value

Aggregate Survey Data

curl -X POST 'http://localhost:8004/api/v1/analytics/aggregate' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "string",
  "question_ids": [
    "string"
  ],
  "chart_type": "string",
  "aggregation": "string",
  "filters": {},
  "grouping": "string",
  "value_mode": "string"
}'

const body = `{
  "survey_id": "string",
  "question_ids": [
    "string"
  ],
  "chart_type": "string",
  "aggregation": "string",
  "filters": {},
  "grouping": "string",
  "value_mode": "string"
}`;

const response = await fetch('http://localhost:8004/api/v1/analytics/aggregate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "string",
  "question_ids": [
    "string"
  ],
  "chart_type": "string",
  "aggregation": "string",
  "filters": {},
  "grouping": "string",
  "value_mode": "string"
}'''

response = requests.post(
    'http://localhost:8004/api/v1/analytics/aggregate',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "string",
  "question_ids": [
    "string"
  ],
  "chart_type": "string",
  "aggregation": "string",
  "filters": {},
  "grouping": "string",
  "value_mode": "string"
}

{
  "survey_id": "string",
  "question_ids": [
    "string"
  ],
  "chart_type": "string",
  "aggregation": "string",
  "data": [
    {
      "label": "string",
      "value": 0,
      "count": 0,
      "extra": {}
    }
  ],
  "summary": {},
  "cached": false,
  "generated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to aggregate survey response data for a chart panel.

survey_idstringrequired

question_idsArray<string>required

chart_typestringrequired

aggregationstringrequired

filtersobject | null

Show child attributes

Any of

object

null

groupingstring | null

Show child attributes

Any of

string

null

value_modestring | null

Show child attributes

Any of

string

null

Response

200OKAnalyticsService_AggregateResponseDTO

Successful Response

Response fields application/json

Aggregated chart data response.

survey_idstringrequired

question_idsArray<string>required

chart_typestringrequired

aggregationstringrequired

dataArray<AnalyticsService_AggregateDataPointDTO>required

Show child attributes

Single data point in aggregated results.

labelstringrequired

valuenumberrequired

countinteger | null

Show child attributes

Any of

integer

null

extraobject | null

Show child attributes

Any of

object

null

summaryobject | null

Show child attributes

Any of

object

null

cachedbooleanfalse

generated_atstring<date-time>required

422Unprocessable EntityAnalyticsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Workspace Service

Workspaces, projects, and workspace members

Workspace Service / Workspaces

Workspaces — Workspace Service

List Workspaces

GET

http://localhost:8006/api/v1/workspaces

List Workspaces

curl -X GET 'http://localhost:8006/api/v1/workspaces?skip=0&limit=20'

const response = await fetch('http://localhost:8006/api/v1/workspaces?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8006/api/v1/workspaces?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "description": "string",
      "status": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

status_filterWorkspaceService_WorkspaceStatus | nullquery

searchstring | nullquery

Response

200OKWorkspaceService_WorkspaceListDTO

Successful Response

Response fields application/json

itemsArray<WorkspaceService_WorkspaceResponseDTO>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Workspace

POST

http://localhost:8006/api/v1/workspaces

Create Workspace

curl -X POST 'http://localhost:8006/api/v1/workspaces' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string"
}'

const body = `{
  "name": "string",
  "description": "string"
}`;

const response = await fetch('http://localhost:8006/api/v1/workspaces', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string"
}'''

response = requests.post(
    'http://localhost:8006/api/v1/workspaces',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

Response

201CreatedWorkspaceService_WorkspaceResponseDTO

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Workspace

GET

http://localhost:8006/api/v1/workspaces/{workspace_id}

Get Workspace

curl -X GET 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

workspace_idstring<uuid>requiredpath

Response

200OKWorkspaceService_WorkspaceResponseDTO

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Workspace

PUT

http://localhost:8006/api/v1/workspaces/{workspace_id}

Update Workspace

curl -X PUT 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "status": "active"
}'

const body = `{
  "name": "string",
  "description": "string",
  "status": "active"
}`;

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "status": "active"
}'''

response = requests.put(
    'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "status": "active"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

statusWorkspaceService_WorkspaceStatus | null

Show child attributes

Any of

WorkspaceService_WorkspaceStatusactivearchivedsuspendeddeleted

null

Parameters

workspace_idstring<uuid>requiredpath

Response

200OKWorkspaceService_WorkspaceResponseDTO

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Workspace

DELETE

http://localhost:8006/api/v1/workspaces/{workspace_id}

Delete Workspace

curl -X DELETE 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

workspace_idstring<uuid>requiredpath

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Workspace Service / Workspace Members

Workspace Members — Workspace Service

List Members

GET

http://localhost:8006/api/v1/workspaces/{workspace_id}/members

List Members

curl -X GET 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members?skip=0&limit=20'

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "role": "string",
      "invited_by": "550e8400-e29b-41d4-a716-446655440000",
      "joined_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "user_email": "string",
      "user_name": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

workspace_idstring<uuid>requiredpath

skipinteger>= 00query

limitinteger[1, 100]20query

Response

200OKWorkspaceService_MemberListDTO

Successful Response

Response fields application/json

itemsArray<WorkspaceService_MemberResponseDTO>required

Show child attributes

idstring<uuid>required

workspace_idstring<uuid>required

user_idstring<uuid>required

tenant_idstring<uuid>required

rolestringrequired

invited_bystring | nullrequired

Show child attributes

Any of

string<uuid>

null

joined_atstring<date-time>required

created_atstring<date-time>required

updated_atstring<date-time>required

user_emailstring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Add Member

POST

http://localhost:8006/api/v1/workspaces/{workspace_id}/members

Add Member

curl -X POST 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "user_id": "string",
  "role": "viewer"
}'

const body = `{
  "user_id": "string",
  "role": "viewer"
}`;

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "user_id": "string",
  "role": "viewer"
}'''

response = requests.post(
    'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "user_id": "string",
  "role": "viewer"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "string",
  "invited_by": "550e8400-e29b-41d4-a716-446655440000",
  "joined_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "user_email": "string",
  "user_name": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

user_idstringrequired

roleWorkspaceService_WorkspaceMemberRoleowneradmineditorviewerresponderviewer

Parameters

workspace_idstring<uuid>requiredpath

Response

201CreatedWorkspaceService_MemberResponseDTO

Successful Response

Response fields application/json

idstring<uuid>required

workspace_idstring<uuid>required

user_idstring<uuid>required

tenant_idstring<uuid>required

rolestringrequired

invited_bystring | nullrequired

Show child attributes

Any of

string<uuid>

null

joined_atstring<date-time>required

created_atstring<date-time>required

updated_atstring<date-time>required

user_emailstring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Member Role

PUT

http://localhost:8006/api/v1/workspaces/{workspace_id}/members/{member_user_id}

Update Member Role

curl -X PUT 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "role": "owner"
}'

const body = `{
  "role": "owner"
}`;

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "role": "owner"
}'''

response = requests.put(
    'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "role": "owner"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "string",
  "invited_by": "550e8400-e29b-41d4-a716-446655440000",
  "joined_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "user_email": "string",
  "user_name": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

roleWorkspaceService_WorkspaceMemberRoleowneradmineditorviewerresponderrequired

Parameters

workspace_idstring<uuid>requiredpath

member_user_idstring<uuid>requiredpath

Response

200OKWorkspaceService_MemberResponseDTO

Successful Response

Response fields application/json

idstring<uuid>required

workspace_idstring<uuid>required

user_idstring<uuid>required

tenant_idstring<uuid>required

rolestringrequired

invited_bystring | nullrequired

Show child attributes

Any of

string<uuid>

null

joined_atstring<date-time>required

created_atstring<date-time>required

updated_atstring<date-time>required

user_emailstring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Remove Member

DELETE

http://localhost:8006/api/v1/workspaces/{workspace_id}/members/{member_user_id}

Remove Member

curl -X DELETE 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/members/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

workspace_idstring<uuid>requiredpath

member_user_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Member Usage

GET

http://localhost:8006/api/v1/workspaces/members/usage

Return the tenant-scoped usage snapshot for the enforced member entitlement.

The current backend limit is membership-row based, not unique tenant seats. A user added to two workspaces consumes two memberships.

Get Member Usage

curl -X GET 'http://localhost:8006/api/v1/workspaces/members/usage'

const response = await fetch('http://localhost:8006/api/v1/workspaces/members/usage', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8006/api/v1/workspaces/members/usage')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Workspace Service / Projects

Projects — Workspace Service

List Projects

GET

http://localhost:8006/api/v1/workspaces/{workspace_id}/projects

List Projects

curl -X GET 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects?skip=0&limit=20'

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "description": "string",
      "status": "string",
      "has_production_activity": false,
      "production_activity_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

workspace_idstring<uuid>requiredpath

skipinteger>= 00query

limitinteger[1, 100]20query

status_filterWorkspaceService_ProjectStatus | nullquery

searchstring | nullquery

Response

200OKWorkspaceService_ProjectListDTO

Successful Response

Response fields application/json

itemsArray<WorkspaceService_ProjectResponseDTO>required

Show child attributes

idstring<uuid>required

workspace_idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

has_production_activitybooleanfalse

production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Project

POST

http://localhost:8006/api/v1/workspaces/{workspace_id}/projects

Create Project

curl -X POST 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string"
}'

const body = `{
  "name": "string",
  "description": "string"
}`;

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string"
}'''

response = requests.post(
    'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "has_production_activity": false,
  "production_activity_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

Parameters

workspace_idstring<uuid>requiredpath

Response

201CreatedWorkspaceService_ProjectResponseDTO

Successful Response

Response fields application/json

idstring<uuid>required

workspace_idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

has_production_activitybooleanfalse

production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Project By Workspace

GET

http://localhost:8006/api/v1/workspaces/{workspace_id}/projects/{project_id}

Get Project By Workspace

curl -X GET 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "has_production_activity": false,
  "production_activity_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

workspace_idstring<uuid>requiredpath

project_idstring<uuid>requiredpath

Response

200OKWorkspaceService_ProjectResponseDTO

Successful Response

Response fields application/json

idstring<uuid>required

workspace_idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

has_production_activitybooleanfalse

production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Project By Workspace

PUT

http://localhost:8006/api/v1/workspaces/{workspace_id}/projects/{project_id}

Update Project By Workspace

curl -X PUT 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "status": "draft"
}'

const body = `{
  "name": "string",
  "description": "string",
  "status": "draft"
}`;

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "status": "draft"
}'''

response = requests.put(
    'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "status": "draft"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "has_production_activity": false,
  "production_activity_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

statusWorkspaceService_ProjectStatus | null

Show child attributes

Any of

WorkspaceService_ProjectStatusdraftactivecompletedarchiveddeleted

null

Parameters

workspace_idstring<uuid>requiredpath

project_idstring<uuid>requiredpath

Response

200OKWorkspaceService_ProjectResponseDTO

Successful Response

Response fields application/json

idstring<uuid>required

workspace_idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

has_production_activitybooleanfalse

production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Project By Workspace

DELETE

http://localhost:8006/api/v1/workspaces/{workspace_id}/projects/{project_id}

Delete Project By Workspace

curl -X DELETE 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000'

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

workspace_idstring<uuid>requiredpath

project_idstring<uuid>requiredpath

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Project Lifecycle

GET

http://localhost:8006/api/v1/workspaces/{workspace_id}/projects/{project_id}/lifecycle

Read the lifecycle state of a project (internal).

Returns status + the monotonic production-activity invariant WITHOUT any user-RBAC requirement, so peer services can gate production operations for enumerator-context callers (who lack PROJECT_READ). Service-token auth only.

Get Project Lifecycle

curl -X GET 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000/lifecycle'

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000/lifecycle', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000/lifecycle')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

workspace_idstring<uuid>requiredpath

project_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Mark Production Activity

POST

http://localhost:8006/api/v1/workspaces/{workspace_id}/projects/{project_id}/production-activity

Mark that production collection has begun for a project (internal).

Sets the durable monotonic invariant has_production_activity — called by peer services (via the survey-service broker) at the first production interview/response/media event. Idempotent; set-only; never cleared.

Project DRAFT -> 409 project_not_active (collection cannot begin)
Project COMPLETED/ARCHIVED with invariant FALSE -> 409 collection_closed
Project ACTIVE -> invariant set to TRUE (no-op if already set)

Mark Production Activity

curl -X POST 'http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000/production-activity'

const response = await fetch('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000/production-activity', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8006/api/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/projects/550e8400-e29b-41d4-a716-446655440000/production-activity')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

workspace_idstring<uuid>requiredpath

project_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityWorkspaceService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Webhook Service

Webhook subscriptions and delivery tracking

Webhook Service / Health

Health — Webhook Service

Webhook Service / Webhook Subscriptions

Webhook Subscriptions — Webhook Service

List Subscriptions

GET

http://localhost:8007/api/v1/webhooks/subscriptions

List all webhook subscriptions for the tenant.

List Subscriptions

curl -X GET 'http://localhost:8007/api/v1/webhooks/subscriptions?skip=0&limit=20'

const response = await fetch('http://localhost:8007/api/v1/webhooks/subscriptions?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8007/api/v1/webhooks/subscriptions?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "url": "string",
      "event_types": [
        "string"
      ],
      "survey_id": "string",
      "project_id": "string",
      "workspace_id": "string",
      "is_active": true,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

is_activeboolean | nullquery

Response

200OKWebhookService_SubscriptionListDTO

Successful Response

Response fields application/json

DTO for list of webhook subscriptions.

itemsArray<WebhookService_SubscriptionResponseDTO>required

Show child attributes

DTO for webhook subscription response.

idstringrequired

namestringrequired

urlstringrequired

event_typesArray<string>required

survey_idstring | nullrequired

Show child attributes

Any of

string

null

project_idstring | nullrequired

Show child attributes

Any of

string

null

workspace_idstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

created_atstring<date-time>required

updated_atstring<date-time>required

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityWebhookService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Create Subscription

POST

http://localhost:8007/api/v1/webhooks/subscriptions

Create a new webhook subscription.

Create Subscription

curl -X POST 'http://localhost:8007/api/v1/webhooks/subscriptions' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "survey_id": "string",
  "project_id": "string",
  "workspace_id": "string",
  "secret": "string"
}'

const body = `{
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "survey_id": "string",
  "project_id": "string",
  "workspace_id": "string",
  "secret": "string"
}`;

const response = await fetch('http://localhost:8007/api/v1/webhooks/subscriptions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "survey_id": "string",
  "project_id": "string",
  "workspace_id": "string",
  "secret": "string"
}'''

response = requests.post(
    'http://localhost:8007/api/v1/webhooks/subscriptions',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "survey_id": "string",
  "project_id": "string",
  "workspace_id": "string",
  "secret": "string"
}

{
  "id": "string",
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "survey_id": "string",
  "project_id": "string",
  "workspace_id": "string",
  "is_active": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

DTO for creating a webhook subscription.

namestringrequired

urlstringrequired

event_typesArray<string>required

survey_idstring | null

Show child attributes

Any of

string

null

project_idstring | null

Show child attributes

Any of

string

null

workspace_idstring | null

Show child attributes

Any of

string

null

secretstring | null

Show child attributes

Any of

string

null

Response

201CreatedWebhookService_SubscriptionResponseDTO

Successful Response

Response fields application/json

DTO for webhook subscription response.

idstringrequired

namestringrequired

urlstringrequired

event_typesArray<string>required

survey_idstring | nullrequired

Show child attributes

Any of

string

null

project_idstring | nullrequired

Show child attributes

Any of

string

null

workspace_idstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntityWebhookService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Subscription

GET

http://localhost:8007/api/v1/webhooks/subscriptions/{subscription_id}

Get a specific webhook subscription.

Get Subscription

curl -X GET 'http://localhost:8007/api/v1/webhooks/subscriptions/string'

const response = await fetch('http://localhost:8007/api/v1/webhooks/subscriptions/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8007/api/v1/webhooks/subscriptions/string')
print(response.text)

{
  "id": "string",
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "survey_id": "string",
  "project_id": "string",
  "workspace_id": "string",
  "is_active": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

subscription_idstringrequiredpath

Response

200OKWebhookService_SubscriptionResponseDTO

Successful Response

Response fields application/json

DTO for webhook subscription response.

idstringrequired

namestringrequired

urlstringrequired

event_typesArray<string>required

survey_idstring | nullrequired

Show child attributes

Any of

string

null

project_idstring | nullrequired

Show child attributes

Any of

string

null

workspace_idstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntityWebhookService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Update Subscription

PUT

http://localhost:8007/api/v1/webhooks/subscriptions/{subscription_id}

Update a webhook subscription.

Update Subscription

curl -X PUT 'http://localhost:8007/api/v1/webhooks/subscriptions/string' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "is_active": true
}'

const body = `{
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "is_active": true
}`;

const response = await fetch('http://localhost:8007/api/v1/webhooks/subscriptions/string', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "is_active": true
}'''

response = requests.put(
    'http://localhost:8007/api/v1/webhooks/subscriptions/string',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "is_active": true
}

{
  "id": "string",
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "survey_id": "string",
  "project_id": "string",
  "workspace_id": "string",
  "is_active": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

DTO for updating a webhook subscription.

namestring | null

Show child attributes

Any of

string

null

urlstring | null

Show child attributes

Any of

string

null

event_typesArray<string> | null

Show child attributes

Any of

Array<string>

null

is_activeboolean | null

Show child attributes

Any of

boolean

null

Parameters

subscription_idstringrequiredpath

Response

200OKWebhookService_SubscriptionResponseDTO

Successful Response

Response fields application/json

DTO for webhook subscription response.

idstringrequired

namestringrequired

urlstringrequired

event_typesArray<string>required

survey_idstring | nullrequired

Show child attributes

Any of

string

null

project_idstring | nullrequired

Show child attributes

Any of

string

null

workspace_idstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntityWebhookService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Delete Subscription

DELETE

http://localhost:8007/api/v1/webhooks/subscriptions/{subscription_id}

Delete a webhook subscription.

Delete Subscription

curl -X DELETE 'http://localhost:8007/api/v1/webhooks/subscriptions/string'

const response = await fetch('http://localhost:8007/api/v1/webhooks/subscriptions/string', {
  method: 'DELETE',
});

const data = await response.text();

import requests

response = requests.delete('http://localhost:8007/api/v1/webhooks/subscriptions/string')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

subscription_idstringrequiredpath

Response

204No Content

Successful Response

422Unprocessable EntityWebhookService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Toggle Subscription

POST

http://localhost:8007/api/v1/webhooks/subscriptions/{subscription_id}/toggle

Toggle subscription active status.

Toggle Subscription

curl -X POST 'http://localhost:8007/api/v1/webhooks/subscriptions/string/toggle'

const response = await fetch('http://localhost:8007/api/v1/webhooks/subscriptions/string/toggle', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8007/api/v1/webhooks/subscriptions/string/toggle')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

subscription_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityWebhookService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Rotate Secret

POST

http://localhost:8007/api/v1/webhooks/subscriptions/{subscription_id}/rotate-secret

Rotate the secret for a webhook subscription.

Rotate Secret

curl -X POST 'http://localhost:8007/api/v1/webhooks/subscriptions/string/rotate-secret'

const response = await fetch('http://localhost:8007/api/v1/webhooks/subscriptions/string/rotate-secret', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8007/api/v1/webhooks/subscriptions/string/rotate-secret')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

subscription_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityWebhookService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Test Webhook

POST

http://localhost:8007/api/v1/webhooks/subscriptions/{subscription_id}/test

Trigger a test event for a specific webhook subscription.

Test Webhook

curl -X POST 'http://localhost:8007/api/v1/webhooks/subscriptions/string/test'

const response = await fetch('http://localhost:8007/api/v1/webhooks/subscriptions/string/test', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8007/api/v1/webhooks/subscriptions/string/test')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

subscription_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityWebhookService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Webhook Service / Webhook Deliveries

Webhook Deliveries — Webhook Service

List Deliveries

GET

http://localhost:8007/api/v1/webhooks/deliveries

List webhook deliveries for the tenant.

List Deliveries

curl -X GET 'http://localhost:8007/api/v1/webhooks/deliveries?skip=0&limit=20'

const response = await fetch('http://localhost:8007/api/v1/webhooks/deliveries?skip=0&limit=20', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8007/api/v1/webhooks/deliveries?skip=0&limit=20')
print(response.text)

{
  "items": [
    {
      "id": "string",
      "subscription_id": "string",
      "event_id": "string",
      "event_type": "string",
      "status": "string",
      "http_status": 0,
      "retry_count": 0,
      "attempted_at": "2024-01-15T09:30:00Z",
      "delivered_at": "2024-01-15T09:30:00Z",
      "error_message": "string",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

subscription_idstring | nullquery

statusstring | nullquery

event_typestring | nullquery

skipinteger>= 00query

limitinteger[1, 100]20query

Response

200OKWebhookService_DeliveryListDTO

Successful Response

Response fields application/json

DTO for list of webhook deliveries.

itemsArray<WebhookService_DeliveryResponseDTO>required

Show child attributes

DTO for webhook delivery response.

idstringrequired

subscription_idstringrequired

event_idstringrequired

event_typestringrequired

statusstringrequired

http_statusinteger | nullrequired

Show child attributes

Any of

integer

null

retry_countintegerrequired

attempted_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

delivered_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

error_messagestring | nullrequired

Show child attributes

Any of

string

null

created_atstring<date-time>required

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityWebhookService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Delivery

GET

http://localhost:8007/api/v1/webhooks/deliveries/{delivery_id}

Get details of a specific webhook delivery.

Get Delivery

curl -X GET 'http://localhost:8007/api/v1/webhooks/deliveries/string'

const response = await fetch('http://localhost:8007/api/v1/webhooks/deliveries/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8007/api/v1/webhooks/deliveries/string')
print(response.text)

{
  "id": "string",
  "subscription_id": "string",
  "event_id": "string",
  "event_type": "string",
  "status": "string",
  "http_status": 0,
  "retry_count": 0,
  "attempted_at": "2024-01-15T09:30:00Z",
  "delivered_at": "2024-01-15T09:30:00Z",
  "error_message": "string",
  "created_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

delivery_idstringrequiredpath

Response

200OKWebhookService_DeliveryResponseDTO

Successful Response

Response fields application/json

DTO for webhook delivery response.

idstringrequired

subscription_idstringrequired

event_idstringrequired

event_typestringrequired

statusstringrequired

http_statusinteger | nullrequired

Show child attributes

Any of

integer

null

retry_countintegerrequired

attempted_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

delivered_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

error_messagestring | nullrequired

Show child attributes

Any of

string

null

created_atstring<date-time>required

422Unprocessable EntityWebhookService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Retry Delivery

POST

http://localhost:8007/api/v1/webhooks/deliveries/{delivery_id}/retry

Manually retry a failed webhook delivery.

Retry Delivery

curl -X POST 'http://localhost:8007/api/v1/webhooks/deliveries/string/retry'

const response = await fetch('http://localhost:8007/api/v1/webhooks/deliveries/string/retry', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8007/api/v1/webhooks/deliveries/string/retry')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

delivery_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityWebhookService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Delivery Stats

GET

http://localhost:8007/api/v1/webhooks/deliveries/stats/overview

Get delivery statistics for the tenant.

Get Delivery Stats

curl -X GET 'http://localhost:8007/api/v1/webhooks/deliveries/stats/overview'

const response = await fetch('http://localhost:8007/api/v1/webhooks/deliveries/stats/overview', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8007/api/v1/webhooks/deliveries/stats/overview')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

ODK Bridge

ODK Aggregate-compatible endpoints: form list, form download, submissions

ODK Bridge / Health

Health — ODK Bridge

ODK Bridge / ODK Forms

ODK Forms — ODK Bridge

List Forms

GET

http://localhost:8009/formList

OpenRosa Form List API Returns XML list of available forms for the device/user

List Forms

curl -X GET 'http://localhost:8009/formList?verbose=true'

const response = await fetch('http://localhost:8009/formList?verbose=true', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8009/formList?verbose=true')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

formIDstringquery

verbosebooleantruequery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityOdkBridge_HTTPValidationError

Validation Error

Response fields application/json

detailArray<OdkBridge_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Download Form

GET

http://localhost:8009/download/{form_id}

Download XForm definition (XML) Converts internal survey schema to ODK XForm format

Download Form

curl -X GET 'http://localhost:8009/download/string'

const response = await fetch('http://localhost:8009/download/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8009/download/string')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

form_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityOdkBridge_HTTPValidationError

Validation Error

Response fields application/json

detailArray<OdkBridge_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

ODK Bridge / ODK Submissions

ODK Submissions — ODK Bridge

Submit Form

POST

http://localhost:8009/submission

OpenRosa Form Submission API Accepts XML submission with optional media attachments

Submit Form

curl -X POST 'http://localhost:8009/submission' \
  --form-string 'xml_submission_file=string'

const form = new FormData();
form.append('xml_submission_file', 'string');
const response = await fetch('http://localhost:8009/submission', {
  method: 'POST',
  headers: {},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('xml_submission_file', (None, 'string')),
    ]
    response = requests.request('POST', 'http://localhost:8009/submission', headers={}, files=files)
    print(response.text)

Request Body

{
  "xml_submission_file": "string",
  "attachments": []
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

xml_submission_filestringrequired

attachmentsArray<string>

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityOdkBridge_HTTPValidationError

Validation Error

Response fields application/json

detailArray<OdkBridge_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Pull From Central

POST

http://localhost:8009/pull-from-central

Trigger a pull of new submissions from ODK Central.

Connects to Central API
Fetches new submissions since last sync
Processes each and pushes to data-service

Pull From Central

curl -X POST 'http://localhost:8009/pull-from-central'

const response = await fetch('http://localhost:8009/pull-from-central', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8009/pull-from-central')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

form_idstring | nullquery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityOdkBridge_HTTPValidationError

Validation Error

Response fields application/json

detailArray<OdkBridge_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Form Service

Form rendering, sessions, drafts, interviews, notes, validation, RID blocks

Get Migration Version

GET

http://localhost:8010/api/v1/migrations/version

Get current Alembic migration version for specific tenant.

Get Migration Version

curl -X GET 'http://localhost:8010/api/v1/migrations/version'

const response = await fetch('http://localhost:8010/api/v1/migrations/version', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8010/api/v1/migrations/version')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Run Cleanup

POST

http://localhost:8010/api/v1/cleanup/run

Run cleanup job to remove expired sessions and drafts.

Args: dry_run: If True, don't actually delete anything tenant_id: Optional specific tenant to cleanup (admin only)

Run Cleanup

curl -X POST 'http://localhost:8010/api/v1/cleanup/run?dry_run=false'

const response = await fetch('http://localhost:8010/api/v1/cleanup/run?dry_run=false', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8010/api/v1/cleanup/run?dry_run=false')
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

dry_runbooleanfalsequery

tenant_idstring | nullquery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Form Service / Health

Health — Form Service

Form Service / Form Rendering

Form Rendering — Form Service

Render form for filling

GET

http://localhost:8010/api/v1/forms/{survey_id}/render

Render a survey form for user to fill. Creates a new session or continues an existing interview session.

Render form for filling

curl -X GET 'http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/render?language=en' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/render?language=en', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/render?language=en',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "form_schema": {},
  "form_html": "string",
  "prefill_data": {},
  "total_pages": 0,
  "current_page": 0,
  "expires_at": "2024-01-15T09:30:00Z",
  "supports_offline": false,
  "lookup_data": {},
  "trigger_questions": [],
  "referee_questions": {}
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring | nullquery

Specific version to render

languagestringenquery

Form language

prefillstring | nullquery

JSON-encoded prefill data

prefill_respondent_idstring | nullquery

Pre-fill from latest response by this respondent_id

prefill_unique_idstring | nullquery

Pre-fill from response matching this unique_id

interview_idstring | nullquery

Continue an existing interview session

Response

200OKFormService_FormRenderResponse

Successful Response

Response fields application/json

Response containing rendered form data.

session_idstring<uuid>required

session_tokenstringrequired

survey_idstring<uuid>required

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

form_schemaobjectrequired

form_htmlstring | null

Show child attributes

Any of

string

null

prefill_dataobject | null

Show child attributes

Any of

object

null

total_pagesintegerrequired

current_pageinteger0

expires_atstring<date-time>required

supports_offlinebooleanfalse

lookup_dataobject | null

Show child attributes

Any of

[key: string]object

Show child attributes

[key: string]object

null

trigger_questionsArray<string>

referee_questionsobject[object Object]

Show child attributes

[key: string]Array<string>

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get pre-fill data from previous response

GET

http://localhost:8010/api/v1/forms/{survey_id}/prefill

Fetch pre-fill data from a previous response by respondent_id or unique_id.

Get pre-fill data from previous response

curl -X GET 'http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/prefill' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/prefill', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/prefill',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "prefill_data": {},
  "source_response_id": "string",
  "source_submitted_at": "string",
  "prefill_fields": [
    "string"
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

respondent_idstring | nullquery

Respondent identifier for repeat respondent pre-fill

unique_idstring | nullquery

Unique ID value from previous response

Response

200OKFormService_PrefillResponse

Successful Response

Response fields application/json

Response containing pre-fill data from a previous response.

prefill_dataobject

Field name to value mapping for pre-fill

source_response_idstringrequired

ID of the source response

source_submitted_atstring | null

When the source response was submitted

Show child attributes

Any of

string

null

prefill_fieldsArray<string>

List of field names that were pre-filled

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Preview form without session

GET

http://localhost:8010/api/v1/forms/{survey_id}/preview

Preview a form schema without creating a session.

Preview form without session

curl -X GET 'http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/preview?language=en' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/preview?language=en', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/preview?language=en',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring | nullquery

languagestringenquery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get offline manifest

GET

http://localhost:8010/api/v1/forms/{survey_id}/manifest

Get manifest for offline form support (service worker).

Get offline manifest

curl -X GET 'http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/manifest' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/manifest', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/forms/550e8400-e29b-41d4-a716-446655440000/manifest',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "manifest_version": "string",
  "form_files": [
    {}
  ],
  "media_files": [
    {}
  ],
  "last_updated": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring<uuid>requiredpath

version_idstring | nullquery

Response

200OKFormService_FormManifestResponse

Successful Response

Response fields application/json

Response for offline form manifest.

survey_idstring<uuid>required

version_idstring | null

Show child attributes

Any of

string<uuid>

null

manifest_versionstringrequired

form_filesArray<object>required

Show child attributes

[key: string]string

media_filesArray<object>required

Show child attributes

[key: string]string

last_updatedstring<date-time>required

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Form Service / Form Submission

Form Submission — Form Service

Submit completed form

POST

http://localhost:8010/api/v1/forms/submit

Submit a completed form response.

Submit completed form

curl -X POST 'http://localhost:8010/api/v1/forms/submit' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "session_token": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "client_timestamp": "2024-01-15T09:30:00Z",
  "duration_seconds": 0,
  "offline_submission": false,
  "offline_queued_at": "2024-01-15T09:30:00Z",
  "edit_response_id": "string",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "language": "string"
}'

const body = `{
  "session_token": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "client_timestamp": "2024-01-15T09:30:00Z",
  "duration_seconds": 0,
  "offline_submission": false,
  "offline_queued_at": "2024-01-15T09:30:00Z",
  "edit_response_id": "string",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "language": "string"
}`;

const response = await fetch('http://localhost:8010/api/v1/forms/submit', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "session_token": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "client_timestamp": "2024-01-15T09:30:00Z",
  "duration_seconds": 0,
  "offline_submission": false,
  "offline_queued_at": "2024-01-15T09:30:00Z",
  "edit_response_id": "string",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "language": "string"
}'''

response = requests.post(
    'http://localhost:8010/api/v1/forms/submit',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "session_token": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "client_timestamp": "2024-01-15T09:30:00Z",
  "duration_seconds": 0,
  "offline_submission": false,
  "offline_queued_at": "2024-01-15T09:30:00Z",
  "edit_response_id": "string",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "language": "string"
}

{
  "success": true,
  "response_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "submitted_at": "2024-01-15T09:30:00Z",
  "validation_errors": [],
  "message": "string",
  "response_language": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to submit a completed form.

session_tokenstringrequired

form_dataobjectrequired

is_completebooleantrue

current_pageinteger | null

Show child attributes

Any of

integer

null

client_timestampstring | null

Show child attributes

Any of

string<date-time>

null

duration_secondsinteger | null

Active form filling duration in seconds, excluding paused time

Show child attributes

Any of

integer[0, 2592000]

null

offline_submissionbooleanfalse

offline_queued_atstring | null

Show child attributes

Any of

string<date-time>

null

edit_response_idstring | null

Show child attributes

Any of

string

null

version_idstring | null

Show child attributes

Any of

string<uuid>

null

interview_idstring | null

Interview execution ID (cross-service correlation)

Show child attributes

Any of

string<uuid>

null

languagestring | null

Language code used for this submission (e.g., 'en', 'es', 'fr')

Show child attributes

Any of

string

null

Response

200OKFormService_FormSubmitResponse

Successful Response

Response fields application/json

Response after form submission.

successbooleanrequired

response_idstring | null

Show child attributes

Any of

string<uuid>

null

session_idstring<uuid>required

version_idstring | null

Show child attributes

Any of

string<uuid>

null

submitted_atstring<date-time>required

validation_errorsArray<object>

messagestring | null

Show child attributes

Any of

string

null

response_languagestring | null

Show child attributes

Any of

string

null

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Submit offline form

POST

http://localhost:8010/api/v1/forms/submit/offline

Submit a form that was filled offline.

Submit offline form

curl -X POST 'http://localhost:8010/api/v1/forms/submit/offline' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "session_token": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "client_timestamp": "2024-01-15T09:30:00Z",
  "duration_seconds": 0,
  "offline_submission": false,
  "offline_queued_at": "2024-01-15T09:30:00Z",
  "edit_response_id": "string",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "language": "string"
}'

const body = `{
  "session_token": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "client_timestamp": "2024-01-15T09:30:00Z",
  "duration_seconds": 0,
  "offline_submission": false,
  "offline_queued_at": "2024-01-15T09:30:00Z",
  "edit_response_id": "string",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "language": "string"
}`;

const response = await fetch('http://localhost:8010/api/v1/forms/submit/offline', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "session_token": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "client_timestamp": "2024-01-15T09:30:00Z",
  "duration_seconds": 0,
  "offline_submission": false,
  "offline_queued_at": "2024-01-15T09:30:00Z",
  "edit_response_id": "string",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "language": "string"
}'''

response = requests.post(
    'http://localhost:8010/api/v1/forms/submit/offline',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "session_token": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "client_timestamp": "2024-01-15T09:30:00Z",
  "duration_seconds": 0,
  "offline_submission": false,
  "offline_queued_at": "2024-01-15T09:30:00Z",
  "edit_response_id": "string",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "language": "string"
}

{
  "success": true,
  "response_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "submitted_at": "2024-01-15T09:30:00Z",
  "validation_errors": [],
  "message": "string",
  "response_language": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to submit a completed form.

session_tokenstringrequired

form_dataobjectrequired

is_completebooleantrue

current_pageinteger | null

Show child attributes

Any of

integer

null

client_timestampstring | null

Show child attributes

Any of

string<date-time>

null

duration_secondsinteger | null

Active form filling duration in seconds, excluding paused time

Show child attributes

Any of

integer[0, 2592000]

null

offline_submissionbooleanfalse

offline_queued_atstring | null

Show child attributes

Any of

string<date-time>

null

edit_response_idstring | null

Show child attributes

Any of

string

null

version_idstring | null

Show child attributes

Any of

string<uuid>

null

interview_idstring | null

Interview execution ID (cross-service correlation)

Show child attributes

Any of

string<uuid>

null

languagestring | null

Language code used for this submission (e.g., 'en', 'es', 'fr')

Show child attributes

Any of

string

null

Response

200OKFormService_FormSubmitResponse

Successful Response

Response fields application/json

Response after form submission.

successbooleanrequired

response_idstring | null

Show child attributes

Any of

string<uuid>

null

session_idstring<uuid>required

version_idstring | null

Show child attributes

Any of

string<uuid>

null

submitted_atstring<date-time>required

validation_errorsArray<object>

messagestring | null

Show child attributes

Any of

string

null

response_languagestring | null

Show child attributes

Any of

string

null

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Validate form data

POST

http://localhost:8010/api/v1/forms/validate

Validate form data without submitting.

Validate form data

curl -X POST 'http://localhost:8010/api/v1/forms/validate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "session_token": "string",
  "form_data": {},
  "validate_all": false,
  "fields_to_validate": [
    "string"
  ]
}'

const body = `{
  "session_token": "string",
  "form_data": {},
  "validate_all": false,
  "fields_to_validate": [
    "string"
  ]
}`;

const response = await fetch('http://localhost:8010/api/v1/forms/validate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "session_token": "string",
  "form_data": {},
  "validate_all": false,
  "fields_to_validate": [
    "string"
  ]
}'''

response = requests.post(
    'http://localhost:8010/api/v1/forms/validate',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "session_token": "string",
  "form_data": {},
  "validate_all": false,
  "fields_to_validate": [
    "string"
  ]
}

{
  "is_valid": true,
  "errors": [],
  "warnings": [],
  "completion_percentage": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to validate form data without submitting.

session_tokenstringrequired

form_dataobjectrequired

validate_allbooleanfalse

fields_to_validateArray<string> | null

Show child attributes

Any of

Array<string>

null

Response

200OKFormService_FormValidateResponse

Successful Response

Response fields application/json

Response with validation results.

is_validbooleanrequired

errorsArray<object>

warningsArray<object>

completion_percentageinteger0

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Form Service / Draft Management

Draft Management — Form Service

List user's drafts

GET

http://localhost:8010/api/v1/forms/drafts

List all drafts for the current user.

List user's drafts

curl -X GET 'http://localhost:8010/api/v1/forms/drafts?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/drafts?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/forms/drafts?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "device_id": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "draft_data": {},
      "current_page": 0,
      "completed_fields_count": 0,
      "total_fields_count": 0,
      "completion_percentage": 0,
      "status": "string",
      "version_token": 1,
      "content_hash": "string",
      "idempotency_key": "string",
      "is_deleted": false,
      "deleted_at": "2024-01-15T09:30:00Z",
      "validation_errors": [],
      "is_auto_saved": false,
      "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
      "reconciled_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "expires_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 20,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring | nullquery

Filter by survey ID

statusstring | nullquery

Filter by status

skipinteger>= 00query

limitinteger[1, 100]20query

Response

200OKFormService_DraftListResponse

Successful Response

Response fields application/json

Response containing list of drafts.

itemsArray<FormService_DraftResponse>required

Show child attributes

Response containing draft information.

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

user_idstring | null

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobjectrequired

current_pageintegerrequired

completed_fields_countintegerrequired

total_fields_countinteger | null

Show child attributes

Any of

integer

null

completion_percentageintegerrequired

statusstringrequired

version_tokeninteger1

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

deleted_atstring | null

Show child attributes

Any of

string<date-time>

null

validation_errorsArray<object>

is_auto_savedbooleanfalse

reconciliation_grant_idstring | null

Show child attributes

Any of

string<uuid>

null

reconciled_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

totalintegerrequired

skipinteger0

limitinteger20

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Create draft

POST

http://localhost:8010/api/v1/forms/drafts

Create a new draft with sync and idempotency support.

Create draft

curl -X POST 'http://localhost:8010/api/v1/forms/drafts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "content_hash": "string",
  "idempotency_key": "string"
}'

const body = `{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "content_hash": "string",
  "idempotency_key": "string"
}`;

const response = await fetch('http://localhost:8010/api/v1/forms/drafts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "content_hash": "string",
  "idempotency_key": "string"
}'''

response = requests.post(
    'http://localhost:8010/api/v1/forms/drafts',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "content_hash": "string",
  "idempotency_key": "string"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "completed_fields_count": 0,
  "total_fields_count": 0,
  "completion_percentage": 0,
  "status": "string",
  "version_token": 1,
  "content_hash": "string",
  "idempotency_key": "string",
  "is_deleted": false,
  "deleted_at": "2024-01-15T09:30:00Z",
  "validation_errors": [],
  "is_auto_saved": false,
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "reconciled_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to create a new draft.

idstring | null

Show child attributes

Any of

string<uuid>

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobject

current_pageinteger0

survey_version_idstring | null

Pinned immutable survey schema version ID

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

Response

201CreatedFormService_DraftResponse

Successful Response

Response fields application/json

Response containing draft information.

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

user_idstring | null

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobjectrequired

current_pageintegerrequired

completed_fields_countintegerrequired

total_fields_countinteger | null

Show child attributes

Any of

integer

null

completion_percentageintegerrequired

statusstringrequired

version_tokeninteger1

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

deleted_atstring | null

Show child attributes

Any of

string<date-time>

null

validation_errorsArray<object>

is_auto_savedbooleanfalse

reconciliation_grant_idstring | null

Show child attributes

Any of

string<uuid>

null

reconciled_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Delta sync drafts

GET

http://localhost:8010/api/v1/forms/drafts/delta

Pull drafts updated since a given cursor timestamp or keyset cursor, including tombstones (Wave 9 / R24).

Delta sync drafts

curl -X GET 'http://localhost:8010/api/v1/forms/drafts/delta?limit=50' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/drafts/delta?limit=50', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/forms/drafts/delta?limit=50',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "device_id": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "draft_data": {},
      "current_page": 0,
      "completed_fields_count": 0,
      "total_fields_count": 0,
      "completion_percentage": 0,
      "status": "string",
      "version_token": 1,
      "content_hash": "string",
      "idempotency_key": "string",
      "is_deleted": false,
      "deleted_at": "2024-01-15T09:30:00Z",
      "validation_errors": [],
      "is_auto_saved": false,
      "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
      "reconciled_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "expires_at": "2024-01-15T09:30:00Z"
    }
  ],
  "server_timestamp": "string",
  "total": 0,
  "has_next": true,
  "next_cursor": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

cursorstring | nullquery

Opaque keyset cursor for delta pagination

updated_sincestring | nullquery

ISO-8601 timestamp cursor (legacy fallback)

limitinteger[1, 100]50query

Response

200OKFormService_DraftDeltaResponse

Successful Response

Response fields application/json

Response containing delta sync drafts since cursor.

itemsArray<FormService_DraftResponse>required

Show child attributes

Response containing draft information.

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

user_idstring | null

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobjectrequired

current_pageintegerrequired

completed_fields_countintegerrequired

total_fields_countinteger | null

Show child attributes

Any of

integer

null

completion_percentageintegerrequired

statusstringrequired

version_tokeninteger1

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

deleted_atstring | null

Show child attributes

Any of

string<date-time>

null

validation_errorsArray<object>

is_auto_savedbooleanfalse

reconciliation_grant_idstring | null

Show child attributes

Any of

string<uuid>

null

reconciled_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

server_timestampstringrequired

totalintegerrequired

has_nextbooleanrequired

next_cursorstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

List all drafts (admin)

GET

http://localhost:8010/api/v1/forms/drafts/all

List all drafts across users (admin only).

List all drafts (admin)

curl -X GET 'http://localhost:8010/api/v1/forms/drafts/all?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/drafts/all?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/forms/drafts/all?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "device_id": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "draft_data": {},
      "current_page": 0,
      "completed_fields_count": 0,
      "total_fields_count": 0,
      "completion_percentage": 0,
      "status": "string",
      "version_token": 1,
      "content_hash": "string",
      "idempotency_key": "string",
      "is_deleted": false,
      "deleted_at": "2024-01-15T09:30:00Z",
      "validation_errors": [],
      "is_auto_saved": false,
      "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
      "reconciled_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "expires_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 20,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring | nullquery

user_idstring | nullquery

statusstring | nullquery

skipinteger>= 00query

limitinteger[1, 100]20query

Response

200OKFormService_DraftListResponse

Successful Response

Response fields application/json

Response containing list of drafts.

itemsArray<FormService_DraftResponse>required

Show child attributes

Response containing draft information.

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

user_idstring | null

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobjectrequired

current_pageintegerrequired

completed_fields_countintegerrequired

total_fields_countinteger | null

Show child attributes

Any of

integer

null

completion_percentageintegerrequired

statusstringrequired

version_tokeninteger1

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

deleted_atstring | null

Show child attributes

Any of

string<date-time>

null

validation_errorsArray<object>

is_auto_savedbooleanfalse

reconciliation_grant_idstring | null

Show child attributes

Any of

string<uuid>

null

reconciled_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

totalintegerrequired

skipinteger0

limitinteger20

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get draft

GET

http://localhost:8010/api/v1/forms/drafts/{draft_id}

Get a specific draft by ID.

Get draft

curl -X GET 'http://localhost:8010/api/v1/forms/drafts/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/drafts/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/forms/drafts/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "completed_fields_count": 0,
  "total_fields_count": 0,
  "completion_percentage": 0,
  "status": "string",
  "version_token": 1,
  "content_hash": "string",
  "idempotency_key": "string",
  "is_deleted": false,
  "deleted_at": "2024-01-15T09:30:00Z",
  "validation_errors": [],
  "is_auto_saved": false,
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "reconciled_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

draft_idstring<uuid>requiredpath

Response

200OKFormService_DraftResponse

Successful Response

Response fields application/json

Response containing draft information.

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

user_idstring | null

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobjectrequired

current_pageintegerrequired

completed_fields_countintegerrequired

total_fields_countinteger | null

Show child attributes

Any of

integer

null

completion_percentageintegerrequired

statusstringrequired

version_tokeninteger1

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

deleted_atstring | null

Show child attributes

Any of

string<date-time>

null

validation_errorsArray<object>

is_auto_savedbooleanfalse

reconciliation_grant_idstring | null

Show child attributes

Any of

string<uuid>

null

reconciled_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Update draft

PUT

http://localhost:8010/api/v1/forms/drafts/{draft_id}

Update an existing draft with optimistic concurrency checks.

Update draft

curl -X PUT 'http://localhost:8010/api/v1/forms/drafts/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "draft_data": {},
  "name": "string",
  "current_page": 0,
  "is_auto_save": false,
  "version_token": 1,
  "device_id": "string",
  "content_hash": "string",
  "idempotency_key": "string"
}'

const body = `{
  "draft_data": {},
  "name": "string",
  "current_page": 0,
  "is_auto_save": false,
  "version_token": 1,
  "device_id": "string",
  "content_hash": "string",
  "idempotency_key": "string"
}`;

const response = await fetch('http://localhost:8010/api/v1/forms/drafts/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "draft_data": {},
  "name": "string",
  "current_page": 0,
  "is_auto_save": false,
  "version_token": 1,
  "device_id": "string",
  "content_hash": "string",
  "idempotency_key": "string"
}'''

response = requests.put(
    'http://localhost:8010/api/v1/forms/drafts/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "draft_data": {},
  "name": "string",
  "current_page": 0,
  "is_auto_save": false,
  "version_token": 1,
  "device_id": "string",
  "content_hash": "string",
  "idempotency_key": "string"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "completed_fields_count": 0,
  "total_fields_count": 0,
  "completion_percentage": 0,
  "status": "string",
  "version_token": 1,
  "content_hash": "string",
  "idempotency_key": "string",
  "is_deleted": false,
  "deleted_at": "2024-01-15T09:30:00Z",
  "validation_errors": [],
  "is_auto_saved": false,
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "reconciled_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z"
}

{
  "error": "DRAFT_CONFLICT",
  "message": "string",
  "draft_id": "550e8400-e29b-41d4-a716-446655440000",
  "server_version_token": 0,
  "client_version_token": 0,
  "server_content_hash": "string",
  "client_content_hash": "string",
  "server_device_id": "string",
  "server_updated_at": "string",
  "server_draft_data": {}
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to update an existing draft.

draft_dataobject | null

Show child attributes

Any of

object

null

namestring | null

Show child attributes

Any of

string

null

current_pageinteger | null

Show child attributes

Any of

integer

null

is_auto_savebooleanfalse

version_tokeninteger>= 11

Expected current server version token

device_idstring | null

Show child attributes

Any of

string

null

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

Parameters

draft_idstring<uuid>requiredpath

Response

200OKFormService_DraftResponse

Successful Response

Response fields application/json

Response containing draft information.

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

user_idstring | null

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobjectrequired

current_pageintegerrequired

completed_fields_countintegerrequired

total_fields_countinteger | null

Show child attributes

Any of

integer

null

completion_percentageintegerrequired

statusstringrequired

version_tokeninteger1

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

deleted_atstring | null

Show child attributes

Any of

string<date-time>

null

validation_errorsArray<object>

is_auto_savedbooleanfalse

reconciliation_grant_idstring | null

Show child attributes

Any of

string<uuid>

null

reconciled_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

409ConflictFormService_DraftConflictResponse

Optimistic concurrency conflict

Response fields application/json

Response returned upon an optimistic concurrency conflict (HTTP 409).

errorstringDRAFT_CONFLICT

messagestringrequired

draft_idstring<uuid>required

server_version_tokenintegerrequired

client_version_tokeninteger | null

Show child attributes

Any of

integer

null

server_content_hashstring | null

Show child attributes

Any of

string

null

client_content_hashstring | null

Show child attributes

Any of

string

null

server_device_idstring | null

Show child attributes

Any of

string

null

server_updated_atstringrequired

server_draft_dataobjectrequired

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Delete draft

DELETE

http://localhost:8010/api/v1/forms/drafts/{draft_id}

Soft-delete a draft with tombstone so stale devices do not resurrect it.

Delete draft

curl -X DELETE 'http://localhost:8010/api/v1/forms/drafts/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/drafts/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8010/api/v1/forms/drafts/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

draft_idstring<uuid>requiredpath

Response

204No Content

Successful Response

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Drain and archive offline draft after authorization revocation

POST

http://localhost:8010/api/v1/forms/drafts/drain-revoked

Validates pre-revocation editing timestamps against historical authorization, setting status to 'archived_revoked'.

Drain and archive offline draft after authorization revocation

curl -X POST 'http://localhost:8010/api/v1/forms/drafts/drain-revoked' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "device_id": "string",
  "version_token": 1,
  "content_hash": "string",
  "idempotency_key": "string",
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "lastModifiedAt": "2024-01-15T09:30:00Z",
  "reconciliation_reason": "string"
}'

const body = `{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "device_id": "string",
  "version_token": 1,
  "content_hash": "string",
  "idempotency_key": "string",
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "lastModifiedAt": "2024-01-15T09:30:00Z",
  "reconciliation_reason": "string"
}`;

const response = await fetch('http://localhost:8010/api/v1/forms/drafts/drain-revoked', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "device_id": "string",
  "version_token": 1,
  "content_hash": "string",
  "idempotency_key": "string",
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "lastModifiedAt": "2024-01-15T09:30:00Z",
  "reconciliation_reason": "string"
}'''

response = requests.post(
    'http://localhost:8010/api/v1/forms/drafts/drain-revoked',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "device_id": "string",
  "version_token": 1,
  "content_hash": "string",
  "idempotency_key": "string",
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "lastModifiedAt": "2024-01-15T09:30:00Z",
  "reconciliation_reason": "string"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "completed_fields_count": 0,
  "total_fields_count": 0,
  "completion_percentage": 0,
  "status": "string",
  "version_token": 1,
  "content_hash": "string",
  "idempotency_key": "string",
  "is_deleted": false,
  "deleted_at": "2024-01-15T09:30:00Z",
  "validation_errors": [],
  "is_auto_saved": false,
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "reconciled_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to drain an offline draft whose user's assignment was revoked.

idstring<uuid>required

Unique draft identifier

survey_idstring<uuid>required

Survey identifier

survey_version_idstring | null

Pinned survey schema version ID

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobject

Answers captured in draft

current_pageinteger0

device_idstringrequired

Attribution device ID (must not be placeholder)

version_tokeninteger>= 11

Client version token

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Reconciliation grant ID

Show child attributes

Any of

string<uuid>

null

lastModifiedAtstring<date-time>required

Timestamp of the last offline edit to the draft

reconciliation_reasonstring | null

Optional domain note or reason

Show child attributes

Any of

string

null

Response

200OKFormService_DraftResponse

Successful Response

Response fields application/json

Response containing draft information.

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

user_idstring | null

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobjectrequired

current_pageintegerrequired

completed_fields_countintegerrequired

total_fields_countinteger | null

Show child attributes

Any of

integer

null

completion_percentageintegerrequired

statusstringrequired

version_tokeninteger1

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

deleted_atstring | null

Show child attributes

Any of

string<date-time>

null

validation_errorsArray<object>

is_auto_savedbooleanfalse

reconciliation_grant_idstring | null

Show child attributes

Any of

string<uuid>

null

reconciled_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Form Service / Session Management

Session Management — Form Service

List user's sessions

GET

http://localhost:8010/api/v1/forms/sessions

List all form sessions for the current user.

List user's sessions

curl -X GET 'http://localhost:8010/api/v1/forms/sessions?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/sessions?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/forms/sessions?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_token": "string",
      "status": "string",
      "current_page": 0,
      "total_pages": 0,
      "progress_percentage": 0,
      "is_offline": true,
      "started_at": "2024-01-15T09:30:00Z",
      "last_activity_at": "2024-01-15T09:30:00Z",
      "expires_at": "2024-01-15T09:30:00Z",
      "completed_at": "2024-01-15T09:30:00Z",
      "response_id": "550e8400-e29b-41d4-a716-446655440000",
      "metadata": {}
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 20,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring | nullquery

Filter by survey ID

statusstring | nullquery

Filter by status

skipinteger>= 00query

limitinteger[1, 100]20query

Response

200OKFormService_SessionListResponse

Successful Response

Response fields application/json

Response containing list of sessions.

itemsArray<FormService_SessionResponse>required

Show child attributes

Response containing session information.

idstring<uuid>required

survey_idstring<uuid>required

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

current_pageintegerrequired

total_pagesinteger | null

Show child attributes

Any of

integer

null

progress_percentageintegerrequired

is_offlinebooleanrequired

started_atstring<date-time>required

last_activity_atstring<date-time>required

expires_atstring<date-time>required

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

response_idstring | null

Show child attributes

Any of

string<uuid>

null

metadataobject[object Object]

totalintegerrequired

skipinteger0

limitinteger20

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

List all sessions (admin)

GET

http://localhost:8010/api/v1/forms/sessions/all

List all form sessions across users (admin only).

List all sessions (admin)

curl -X GET 'http://localhost:8010/api/v1/forms/sessions/all?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/sessions/all?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/forms/sessions/all?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_token": "string",
      "status": "string",
      "current_page": 0,
      "total_pages": 0,
      "progress_percentage": 0,
      "is_offline": true,
      "started_at": "2024-01-15T09:30:00Z",
      "last_activity_at": "2024-01-15T09:30:00Z",
      "expires_at": "2024-01-15T09:30:00Z",
      "completed_at": "2024-01-15T09:30:00Z",
      "response_id": "550e8400-e29b-41d4-a716-446655440000",
      "metadata": {}
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 20,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring | nullquery

user_idstring | nullquery

statusstring | nullquery

skipinteger>= 00query

limitinteger[1, 100]20query

Response

200OKFormService_SessionListResponse

Successful Response

Response fields application/json

Response containing list of sessions.

itemsArray<FormService_SessionResponse>required

Show child attributes

Response containing session information.

idstring<uuid>required

survey_idstring<uuid>required

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

current_pageintegerrequired

total_pagesinteger | null

Show child attributes

Any of

integer

null

progress_percentageintegerrequired

is_offlinebooleanrequired

started_atstring<date-time>required

last_activity_atstring<date-time>required

expires_atstring<date-time>required

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

response_idstring | null

Show child attributes

Any of

string<uuid>

null

metadataobject[object Object]

totalintegerrequired

skipinteger0

limitinteger20

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get session

GET

http://localhost:8010/api/v1/forms/sessions/{session_id}

Get a specific session by ID.

Get session

curl -X GET 'http://localhost:8010/api/v1/forms/sessions/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/sessions/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/forms/sessions/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "status": "string",
  "current_page": 0,
  "total_pages": 0,
  "progress_percentage": 0,
  "is_offline": true,
  "started_at": "2024-01-15T09:30:00Z",
  "last_activity_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "response_id": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {}
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

session_idstring<uuid>requiredpath

Response

200OKFormService_SessionResponse

Successful Response

Response fields application/json

Response containing session information.

idstring<uuid>required

survey_idstring<uuid>required

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

current_pageintegerrequired

total_pagesinteger | null

Show child attributes

Any of

integer

null

progress_percentageintegerrequired

is_offlinebooleanrequired

started_atstring<date-time>required

last_activity_atstring<date-time>required

expires_atstring<date-time>required

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

response_idstring | null

Show child attributes

Any of

string<uuid>

null

metadataobject[object Object]

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Delete session

DELETE

http://localhost:8010/api/v1/forms/sessions/{session_id}

Delete/invalidate a session.

Delete session

curl -X DELETE 'http://localhost:8010/api/v1/forms/sessions/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/forms/sessions/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8010/api/v1/forms/sessions/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

session_idstring<uuid>requiredpath

Response

204No Content

Successful Response

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get session by token

GET

http://localhost:8010/api/v1/forms/sessions/token/{session_token}

Get a session by its token.

Get session by token

curl -X GET 'http://localhost:8010/api/v1/forms/sessions/token/string'

const response = await fetch('http://localhost:8010/api/v1/forms/sessions/token/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8010/api/v1/forms/sessions/token/string')
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "status": "string",
  "current_page": 0,
  "total_pages": 0,
  "progress_percentage": 0,
  "is_offline": true,
  "started_at": "2024-01-15T09:30:00Z",
  "last_activity_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "response_id": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {}
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

session_tokenstringrequiredpath

Response

200OKFormService_SessionResponse

Successful Response

Response fields application/json

Response containing session information.

idstring<uuid>required

survey_idstring<uuid>required

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

current_pageintegerrequired

total_pagesinteger | null

Show child attributes

Any of

integer

null

progress_percentageintegerrequired

is_offlinebooleanrequired

started_atstring<date-time>required

last_activity_atstring<date-time>required

expires_atstring<date-time>required

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

response_idstring | null

Show child attributes

Any of

string<uuid>

null

metadataobject[object Object]

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Form Service / Lookups

Lookups — Form Service

Resolve lookup values

GET

http://localhost:8010/api/v1/forms/{session_token}/lookup

Resolve referee question values from lookup data based on trigger question answer.

Resolve lookup values

curl -X GET 'http://localhost:8010/api/v1/forms/string/lookup?trigger_question=string&trigger_value=string'

const response = await fetch('http://localhost:8010/api/v1/forms/string/lookup?trigger_question=string&trigger_value=string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8010/api/v1/forms/string/lookup?trigger_question=string&trigger_value=string')
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

session_tokenstringrequiredpath

trigger_questionstringrequiredquery

Name of trigger question (e.g., 'uid')

trigger_valuestringrequiredquery

Value answered for trigger question

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Form Service / Validation

Validation — Form Service

Validate single field constraint

POST

http://localhost:8010/api/v1/validation/field

Validate a single field against its XPath constraint

Validate single field constraint

curl -X POST 'http://localhost:8010/api/v1/validation/field' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "session_token": "string",
  "field_name": "string",
  "form_data": {}
}'

const body = `{
  "session_token": "string",
  "field_name": "string",
  "form_data": {}
}`;

const response = await fetch('http://localhost:8010/api/v1/validation/field', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "session_token": "string",
  "field_name": "string",
  "form_data": {}
}'''

response = requests.post(
    'http://localhost:8010/api/v1/validation/field',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "session_token": "string",
  "field_name": "string",
  "form_data": {}
}

{
  "is_valid": true,
  "field": "string",
  "errors": [
    {}
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to validate a single field.

session_tokenstringrequired

Form session token

field_namestringrequired

Name of the field to validate

field_valueanyrequired

Current value of the field

form_dataobject

Complete form data

Response

200OKFormService_ValidateFieldResponse

Successful Response

Response fields application/json

Response for single field validation.

is_validbooleanrequired

fieldstringrequired

errorsArray<object>

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Validate entire form

POST

http://localhost:8010/api/v1/validation/form

Validate all field constraints in a form

Validate entire form

curl -X POST 'http://localhost:8010/api/v1/validation/form' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "session_token": "string",
  "form_data": {},
  "fields_to_validate": [
    "string"
  ]
}'

const body = `{
  "session_token": "string",
  "form_data": {},
  "fields_to_validate": [
    "string"
  ]
}`;

const response = await fetch('http://localhost:8010/api/v1/validation/form', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "session_token": "string",
  "form_data": {},
  "fields_to_validate": [
    "string"
  ]
}'''

response = requests.post(
    'http://localhost:8010/api/v1/validation/form',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "session_token": "string",
  "form_data": {},
  "fields_to_validate": [
    "string"
  ]
}

{
  "is_valid": true,
  "errors": [
    {}
  ],
  "total_fields": 0,
  "valid_fields": 0,
  "invalid_fields": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to validate entire form.

session_tokenstringrequired

Form session token

form_dataobjectrequired

Form data to validate

fields_to_validateArray<string> | null

Optional list of fields to validate (all if not specified)

Show child attributes

Any of

Array<string>

null

Response

200OKFormService_ValidateFormResponse

Successful Response

Response fields application/json

Response for form validation.

is_validbooleanrequired

errorsArray<object>

total_fieldsintegerrequired

valid_fieldsintegerrequired

invalid_fieldsintegerrequired

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Evaluate XPath expression

POST

http://localhost:8010/api/v1/validation/evaluate

Evaluate an XPath expression with form data context

Evaluate XPath expression

curl -X POST 'http://localhost:8010/api/v1/validation/evaluate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "session_token": "string",
  "expression": "string",
  "form_data": {}
}'

const body = `{
  "session_token": "string",
  "expression": "string",
  "form_data": {}
}`;

const response = await fetch('http://localhost:8010/api/v1/validation/evaluate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "session_token": "string",
  "expression": "string",
  "form_data": {}
}'''

response = requests.post(
    'http://localhost:8010/api/v1/validation/evaluate',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "session_token": "string",
  "expression": "string",
  "form_data": {}
}

{
  "success": true,
  "error": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to evaluate an XPath expression.

session_tokenstringrequired

Form session token

expressionstringrequired

XPath expression to evaluate

form_dataobject

Form data for variable resolution

Response

200OKFormService_EvaluateExpressionResponse

Successful Response

Response fields application/json

Response for expression evaluation.

successbooleanrequired

resultany

errorstring | null

Show child attributes

Any of

string

null

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

List available XPath functions

GET

http://localhost:8010/api/v1/validation/functions

Get list of all available XPath/ODK functions

List available XPath functions

curl -X GET 'http://localhost:8010/api/v1/validation/functions' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/validation/functions', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/validation/functions',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Authorization

HTTPBearerhttp (bearer)

Test constraint expression

POST

http://localhost:8010/api/v1/validation/test-constraint

Test a constraint expression with sample data

Test constraint expression

curl -X POST 'http://localhost:8010/api/v1/validation/test-constraint?constraint=string&field_name=test_field' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'

const response = await fetch('http://localhost:8010/api/v1/validation/test-constraint?constraint=string&field_name=test_field', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body: '{}',
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8010/api/v1/validation/test-constraint?constraint=string&field_name=test_field',
    data='{}'.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

object[object Object]

Parameters

constraintstringrequiredquery

field_namestringtest_fieldquery

field_valueanyquery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Form Service / RID Block Allocation

RID Block Allocation — Form Service

List RID block allocations

GET

http://localhost:8010/api/v1/interviews/rid-blocks

List RID block allocations for the tenant. Field users see their own blocks.

List RID block allocations

curl -X GET 'http://localhost:8010/api/v1/interviews/rid-blocks?limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/rid-blocks?limit=50&offset=0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/interviews/rid-blocks?limit=50&offset=0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_code": "string",
      "device_id": "string",
      "start_seq": 0,
      "end_seq": 0,
      "current_seq": 0,
      "is_exhausted": false,
      "idempotency_key": "string",
      "created_at": "string"
    }
  ],
  "total": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring | nullquery

Filter by survey ID

device_idstring | nullquery

Filter by device ID

limitinteger[1, 100]50query

offsetinteger>= 00query

Response

200OKFormService_RidBlockListResponse

Successful Response

Response fields application/json

List of RID block allocations.

itemsArray<FormService_RidBlockResponse>required

Show child attributes

Server-allocated device-bound RID block response (matches mobile RidBlockDto).

idstring<uuid>required

tenant_idstring<uuid>required

survey_idstring<uuid>required

user_idstring<uuid>required

user_codestringrequired

device_idstringrequired

start_seqintegerrequired

end_seqintegerrequired

current_seqintegerrequired

is_exhaustedbooleanfalse

idempotency_keystring | null

Show child attributes

Any of

string

null

created_atstringrequired

totalintegerrequired

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Allocate server-issued device-bound RID block

POST

http://localhost:8010/api/v1/interviews/rid-blocks

Allocate a non-overlapping block of RIDs bound to (tenant, survey, user, device) (R25 / AD-3).

Allocate server-issued device-bound RID block

curl -X POST 'http://localhost:8010/api/v1/interviews/rid-blocks' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "block_size": 50,
  "idempotency_key": "string"
}'

const body = `{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "block_size": 50,
  "idempotency_key": "string"
}`;

const response = await fetch('http://localhost:8010/api/v1/interviews/rid-blocks', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "block_size": 50,
  "idempotency_key": "string"
}'''

response = requests.post(
    'http://localhost:8010/api/v1/interviews/rid-blocks',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "block_size": 50,
  "idempotency_key": "string"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_code": "string",
  "device_id": "string",
  "start_seq": 0,
  "end_seq": 0,
  "current_seq": 0,
  "is_exhausted": false,
  "idempotency_key": "string",
  "created_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request payload for server-allocated device-bound RID block (R25 / AD-3).

survey_idstring<uuid>required

ID of the survey for which RID block is requested

device_idstringrequired

Unique client device ID (non-placeholder)

block_sizeinteger[1, 200]50

Number of sequential RIDs to allocate

idempotency_keystring | null

Client idempotency key for safe retries

Show child attributes

Any of

string

null

Response

201CreatedFormService_RidBlockResponse

Successful Response

Response fields application/json

Server-allocated device-bound RID block response (matches mobile RidBlockDto).

idstring<uuid>required

tenant_idstring<uuid>required

survey_idstring<uuid>required

user_idstring<uuid>required

user_codestringrequired

device_idstringrequired

start_seqintegerrequired

end_seqintegerrequired

current_seqintegerrequired

is_exhaustedbooleanfalse

idempotency_keystring | null

Show child attributes

Any of

string

null

created_atstringrequired

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Form Service / Interview Management

Interview Management — Form Service

List interviews

GET

http://localhost:8010/api/v1/interviews

List interviews

curl -X GET 'http://localhost:8010/api/v1/interviews?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/interviews?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
      "interviewer_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_token": "string",
      "status": "string",
      "started_at": "2024-01-15T09:30:00Z",
      "paused_at": "2024-01-15T09:30:00Z",
      "completed_at": "2024-01-15T09:30:00Z",
      "terminated_at": "2024-01-15T09:30:00Z",
      "termination_reason": "string",
      "last_heartbeat_at": "2024-01-15T09:30:00Z",
      "language": "string",
      "interview_metadata": {},
      "current_page": 0,
      "answered_count": 0,
      "total_questions": 0,
      "survey_name": "string",
      "response_rid": "string",
      "response_uid": "string",
      "current_response_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 20,
  "has_next": false,
  "has_previous": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

status_filterstring | nullquery

Filter by status

survey_idstring | nullquery

Filter by survey ID

interviewer_idstring | nullquery

Filter by interviewer

respondent_idstring | nullquery

Filter by respondent

searchstring | nullquery

Search by session token

sortstring | nullquery

Sort by: last_activity, started_at, completion, created_at

skipinteger>= 00query

limitinteger[1, 100]20query

Response

200OKFormService_InterviewListResponse

Successful Response

Response fields application/json

itemsArray<FormService_InterviewDto>required

Show child attributes

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_idstring<uuid>required

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

interviewer_idstring | null

Show child attributes

Any of

string<uuid>

null

session_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

started_atstring | null

Show child attributes

Any of

string<date-time>

null

paused_atstring | null

Show child attributes

Any of

string<date-time>

null

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

terminated_atstring | null

Show child attributes

Any of

string<date-time>

null

termination_reasonstring | null

Show child attributes

Any of

string

null

last_heartbeat_atstring | null

Show child attributes

Any of

string<date-time>

null

languagestring | null

Show child attributes

Any of

string

null

interview_metadataobject[object Object]

current_pageinteger0

answered_countinteger0

total_questionsinteger0

survey_namestring | null

Show child attributes

Any of

string

null

response_ridstring | null

Show child attributes

Any of

string

null

response_uidstring | null

Show child attributes

Any of

string

null

current_response_idstring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

updated_atstring<date-time>required

totalintegerrequired

skipinteger0

limitinteger20

has_nextbooleanfalse

has_previousbooleanfalse

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Create interview

POST

http://localhost:8010/api/v1/interviews

Create interview

curl -X POST 'http://localhost:8010/api/v1/interviews' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "total_questions": 0,
  "language": "string",
  "interview_metadata": {},
  "survey_name": "string",
  "response_rid": "string"
}'

const body = `{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "total_questions": 0,
  "language": "string",
  "interview_metadata": {},
  "survey_name": "string",
  "response_rid": "string"
}`;

const response = await fetch('http://localhost:8010/api/v1/interviews', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "total_questions": 0,
  "language": "string",
  "interview_metadata": {},
  "survey_name": "string",
  "response_rid": "string"
}'''

response = requests.post(
    'http://localhost:8010/api/v1/interviews',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "total_questions": 0,
  "language": "string",
  "interview_metadata": {},
  "survey_name": "string",
  "response_rid": "string"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "interviewer_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "status": "string",
  "started_at": "2024-01-15T09:30:00Z",
  "paused_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "terminated_at": "2024-01-15T09:30:00Z",
  "termination_reason": "string",
  "last_heartbeat_at": "2024-01-15T09:30:00Z",
  "language": "string",
  "interview_metadata": {},
  "current_page": 0,
  "answered_count": 0,
  "total_questions": 0,
  "survey_name": "string",
  "response_rid": "string",
  "response_uid": "string",
  "current_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

survey_idstring<uuid>required

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

total_questionsinteger0

languagestring | null

Active language code during interview (e.g., 'en', 'es', 'hi')

Show child attributes

Any of

string

null

interview_metadataobject[object Object]

survey_namestring | null

Show child attributes

Any of

string

null

response_ridstring | null

DEPRECATED. The server allocates the permanent RID at interview creation. This field is ignored for NEW interviews and only used as a last-resort backfill for legacy interviews created before server-side allocation.

Show child attributes

Any of

string

null

Response

201CreatedFormService_InterviewDto

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_idstring<uuid>required

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

interviewer_idstring | null

Show child attributes

Any of

string<uuid>

null

session_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

started_atstring | null

Show child attributes

Any of

string<date-time>

null

paused_atstring | null

Show child attributes

Any of

string<date-time>

null

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

terminated_atstring | null

Show child attributes

Any of

string<date-time>

null

termination_reasonstring | null

Show child attributes

Any of

string

null

last_heartbeat_atstring | null

Show child attributes

Any of

string<date-time>

null

languagestring | null

Show child attributes

Any of

string

null

interview_metadataobject[object Object]

current_pageinteger0

answered_countinteger0

total_questionsinteger0

survey_namestring | null

Show child attributes

Any of

string

null

response_ridstring | null

Show child attributes

Any of

string

null

response_uidstring | null

Show child attributes

Any of

string

null

current_response_idstring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Resolve interview by session token

GET

http://localhost:8010/api/v1/interviews/resolve/by-session-token/{session_token}

Resolve interview by session token

curl -X GET 'http://localhost:8010/api/v1/interviews/resolve/by-session-token/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/resolve/by-session-token/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/interviews/resolve/by-session-token/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "interviewer_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "status": "string",
  "started_at": "2024-01-15T09:30:00Z",
  "paused_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "terminated_at": "2024-01-15T09:30:00Z",
  "termination_reason": "string",
  "last_heartbeat_at": "2024-01-15T09:30:00Z",
  "language": "string",
  "interview_metadata": {},
  "current_page": 0,
  "answered_count": 0,
  "total_questions": 0,
  "survey_name": "string",
  "response_rid": "string",
  "response_uid": "string",
  "current_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

session_tokenstringrequiredpath

Response

200OKFormService_InterviewDto

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_idstring<uuid>required

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

interviewer_idstring | null

Show child attributes

Any of

string<uuid>

null

session_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

started_atstring | null

Show child attributes

Any of

string<date-time>

null

paused_atstring | null

Show child attributes

Any of

string<date-time>

null

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

terminated_atstring | null

Show child attributes

Any of

string<date-time>

null

termination_reasonstring | null

Show child attributes

Any of

string

null

last_heartbeat_atstring | null

Show child attributes

Any of

string<date-time>

null

languagestring | null

Show child attributes

Any of

string

null

interview_metadataobject[object Object]

current_pageinteger0

answered_countinteger0

total_questionsinteger0

survey_namestring | null

Show child attributes

Any of

string

null

response_ridstring | null

Show child attributes

Any of

string

null

response_uidstring | null

Show child attributes

Any of

string

null

current_response_idstring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get interview details

GET

http://localhost:8010/api/v1/interviews/{interview_id}

Get interview details

curl -X GET 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "interviewer_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "status": "string",
  "started_at": "2024-01-15T09:30:00Z",
  "paused_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "terminated_at": "2024-01-15T09:30:00Z",
  "termination_reason": "string",
  "last_heartbeat_at": "2024-01-15T09:30:00Z",
  "language": "string",
  "interview_metadata": {},
  "current_page": 0,
  "answered_count": 0,
  "total_questions": 0,
  "survey_name": "string",
  "response_rid": "string",
  "response_uid": "string",
  "current_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

interview_idstring<uuid>requiredpath

Response

200OKFormService_InterviewDto

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_idstring<uuid>required

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

interviewer_idstring | null

Show child attributes

Any of

string<uuid>

null

session_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

started_atstring | null

Show child attributes

Any of

string<date-time>

null

paused_atstring | null

Show child attributes

Any of

string<date-time>

null

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

terminated_atstring | null

Show child attributes

Any of

string<date-time>

null

termination_reasonstring | null

Show child attributes

Any of

string

null

last_heartbeat_atstring | null

Show child attributes

Any of

string<date-time>

null

languagestring | null

Show child attributes

Any of

string

null

interview_metadataobject[object Object]

current_pageinteger0

answered_countinteger0

total_questionsinteger0

survey_namestring | null

Show child attributes

Any of

string

null

response_ridstring | null

Show child attributes

Any of

string

null

response_uidstring | null

Show child attributes

Any of

string

null

current_response_idstring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Soft-delete interview (only if status is created)

DELETE

http://localhost:8010/api/v1/interviews/{interview_id}

Soft-delete interview (only if status is created)

curl -X DELETE 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

interview_idstring<uuid>requiredpath

Response

204No Content

Successful Response

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Update interview metadata

PATCH

http://localhost:8010/api/v1/interviews/{interview_id}

Update interview metadata

curl -X PATCH 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "current_page": 0,
  "answered_count": 0,
  "total_questions": 0,
  "interview_metadata": {}
}'

const body = `{
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "current_page": 0,
  "answered_count": 0,
  "total_questions": 0,
  "interview_metadata": {}
}`;

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "current_page": 0,
  "answered_count": 0,
  "total_questions": 0,
  "interview_metadata": {}
}'''

response = requests.patch(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "current_page": 0,
  "answered_count": 0,
  "total_questions": 0,
  "interview_metadata": {}
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "interviewer_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "status": "string",
  "started_at": "2024-01-15T09:30:00Z",
  "paused_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "terminated_at": "2024-01-15T09:30:00Z",
  "termination_reason": "string",
  "last_heartbeat_at": "2024-01-15T09:30:00Z",
  "language": "string",
  "interview_metadata": {},
  "current_page": 0,
  "answered_count": 0,
  "total_questions": 0,
  "survey_name": "string",
  "response_rid": "string",
  "response_uid": "string",
  "current_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

current_pageinteger | null

Show child attributes

Any of

integer

null

answered_countinteger | null

Show child attributes

Any of

integer

null

total_questionsinteger | null

Show child attributes

Any of

integer

null

interview_metadataobject | null

Show child attributes

Any of

object

null

Parameters

interview_idstring<uuid>requiredpath

Response

200OKFormService_InterviewDto

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_idstring<uuid>required

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

interviewer_idstring | null

Show child attributes

Any of

string<uuid>

null

session_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

started_atstring | null

Show child attributes

Any of

string<date-time>

null

paused_atstring | null

Show child attributes

Any of

string<date-time>

null

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

terminated_atstring | null

Show child attributes

Any of

string<date-time>

null

termination_reasonstring | null

Show child attributes

Any of

string

null

last_heartbeat_atstring | null

Show child attributes

Any of

string<date-time>

null

languagestring | null

Show child attributes

Any of

string

null

interview_metadataobject[object Object]

current_pageinteger0

answered_countinteger0

total_questionsinteger0

survey_namestring | null

Show child attributes

Any of

string

null

response_ridstring | null

Show child attributes

Any of

string

null

response_uidstring | null

Show child attributes

Any of

string

null

current_response_idstring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Transition interview status

POST

http://localhost:8010/api/v1/interviews/{interview_id}/transition

Transition interview status

curl -X POST 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/transition' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "to_status": "string",
  "termination_reason": "string",
  "explanatory_text": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "version_id": "string",
  "edit_response_id": "string",
  "duration_seconds": 0,
  "question_paradata": {}
}'

const body = `{
  "to_status": "string",
  "termination_reason": "string",
  "explanatory_text": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "version_id": "string",
  "edit_response_id": "string",
  "duration_seconds": 0,
  "question_paradata": {}
}`;

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/transition', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "to_status": "string",
  "termination_reason": "string",
  "explanatory_text": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "version_id": "string",
  "edit_response_id": "string",
  "duration_seconds": 0,
  "question_paradata": {}
}'''

response = requests.post(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/transition',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "to_status": "string",
  "termination_reason": "string",
  "explanatory_text": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "version_id": "string",
  "edit_response_id": "string",
  "duration_seconds": 0,
  "question_paradata": {}
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "interviewer_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "status": "string",
  "started_at": "2024-01-15T09:30:00Z",
  "paused_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "terminated_at": "2024-01-15T09:30:00Z",
  "termination_reason": "string",
  "last_heartbeat_at": "2024-01-15T09:30:00Z",
  "language": "string",
  "interview_metadata": {},
  "current_page": 0,
  "answered_count": 0,
  "total_questions": 0,
  "survey_name": "string",
  "response_rid": "string",
  "response_uid": "string",
  "current_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

to_statusstringrequired

termination_reasonstring | null

Show child attributes

Any of

string

null

explanatory_textstring | null

Show child attributes

Any of

string

null

form_dataobject | null

Show child attributes

Any of

object

null

is_completeboolean | null

Show child attributes

Any of

boolean

null

current_pageinteger | null

Show child attributes

Any of

integer

null

version_idstring | null

Show child attributes

Any of

string

null

edit_response_idstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

question_paradataobject | null

Phase-1 question paradata (T). Additive — merged into InterviewExecution.interview_metadata.question_paradata before the transition, and forwarded to data-service response_metadata at completion/retained termination. Existing metadata keys are preserved.

Show child attributes

Any of

object

null

Parameters

interview_idstring<uuid>requiredpath

Response

200OKFormService_InterviewDto

Successful Response

Response fields application/json

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_idstring<uuid>required

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

interviewer_idstring | null

Show child attributes

Any of

string<uuid>

null

session_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

started_atstring | null

Show child attributes

Any of

string<date-time>

null

paused_atstring | null

Show child attributes

Any of

string<date-time>

null

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

terminated_atstring | null

Show child attributes

Any of

string<date-time>

null

termination_reasonstring | null

Show child attributes

Any of

string

null

last_heartbeat_atstring | null

Show child attributes

Any of

string<date-time>

null

languagestring | null

Show child attributes

Any of

string

null

interview_metadataobject[object Object]

current_pageinteger0

answered_countinteger0

total_questionsinteger0

survey_namestring | null

Show child attributes

Any of

string

null

response_ridstring | null

Show child attributes

Any of

string

null

response_uidstring | null

Show child attributes

Any of

string

null

current_response_idstring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

updated_atstring<date-time>required

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get termination details for an interview

GET

http://localhost:8010/api/v1/interviews/{interview_id}/termination

Get termination details for an interview

curl -X GET 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/termination' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/termination', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/termination',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "termination_reason": "string",
  "explanatory_text": "string",
  "retain_partial_data": true,
  "discard_data": true,
  "notify_supervisor": true,
  "supervisor_notified": true,
  "supervisor_notified_at": "2024-01-15T09:30:00Z",
  "data_action_taken": "string",
  "terminated_by": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

interview_idstring<uuid>requiredpath

Response

200OKFormService_TerminationDto

Successful Response

Response fields application/json

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

termination_reasonstringrequired

explanatory_textstring | null

Show child attributes

Any of

string

null

retain_partial_databooleanrequired

discard_databooleanrequired

notify_supervisorbooleanrequired

supervisor_notifiedbooleanrequired

supervisor_notified_atstring | null

Show child attributes

Any of

string<date-time>

null

data_action_takenstring | null

Show child attributes

Any of

string

null

terminated_bystring<uuid>required

created_atstring<date-time>required

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

List all termination reason options with policies

GET

http://localhost:8010/api/v1/interviews/termination-policies

List all termination reason options with policies

curl -X GET 'http://localhost:8010/api/v1/interviews/termination-policies' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/termination-policies', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/interviews/termination-policies',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

[
  {
    "code": "string",
    "display_label": "string",
    "policy": {
      "retain_partial_data": true,
      "discard_data": true,
      "notify_supervisor": true,
      "requires_explanatory_text": true
    }
  }
]

Response

200OKArray<FormService_TerminationReasonOptionDto>

Successful Response

Response fields application/json

Array<FormService_TerminationReasonOptionDto>

Show child attributes

codestringrequired

display_labelstringrequired

policyFormService_TerminationPolicyDtorequired

Show child attributes

retain_partial_databooleanrequired

discard_databooleanrequired

notify_supervisorbooleanrequired

requires_explanatory_textbooleanrequired

Authorization

HTTPBearerhttp (bearer)

Retry pending partial submission for terminated interview

POST

http://localhost:8010/api/v1/interviews/{interview_id}/retry-submission

Retry a pending partial submission for a terminated interview.

This is used when the initial submission failed and the user wants to manually retry, or when the sync engine automatically retries during crash recovery.

Retry pending partial submission for terminated interview

curl -X POST 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/retry-submission' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/retry-submission', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/retry-submission',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "termination_reason": "string",
  "explanatory_text": "string",
  "retain_partial_data": true,
  "discard_data": true,
  "notify_supervisor": true,
  "supervisor_notified": true,
  "supervisor_notified_at": "2024-01-15T09:30:00Z",
  "data_action_taken": "string",
  "terminated_by": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

interview_idstring<uuid>requiredpath

Response

200OKFormService_TerminationDto

Successful Response

Response fields application/json

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

termination_reasonstringrequired

explanatory_textstring | null

Show child attributes

Any of

string

null

retain_partial_databooleanrequired

discard_databooleanrequired

notify_supervisorbooleanrequired

supervisor_notifiedbooleanrequired

supervisor_notified_atstring | null

Show child attributes

Any of

string<date-time>

null

data_action_takenstring | null

Show child attributes

Any of

string

null

terminated_bystring<uuid>required

created_atstring<date-time>required

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Heartbeat ping for active interview

POST

http://localhost:8010/api/v1/interviews/{interview_id}/heartbeat

Heartbeat ping for active interview

curl -X POST 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/heartbeat' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/heartbeat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/heartbeat',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

interview_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

List interview events

GET

http://localhost:8010/api/v1/interviews/{interview_id}/events

List interview events

curl -X GET 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/events?skip=0&limit=50' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/events?skip=0&limit=50', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/events?skip=0&limit=50',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "interview_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "from_status": "string",
    "to_status": "string",
    "triggered_by": "550e8400-e29b-41d4-a716-446655440000",
    "event_metadata": {},
    "created_at": "2024-01-15T09:30:00Z"
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

interview_idstring<uuid>requiredpath

skipinteger>= 00query

limitinteger[1, 200]50query

Response

200OKArray<FormService_InterviewEventDto>

Successful Response

Response fields application/json

Array<FormService_InterviewEventDto>

Show child attributes

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

from_statusstring | null

Show child attributes

Any of

string

null

to_statusstringrequired

triggered_bystring | null

Show child attributes

Any of

string<uuid>

null

event_metadataobject[object Object]

created_atstring<date-time>required

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Form Service / Interview Notes

Interview Notes — Form Service

List notes for an interview

GET

http://localhost:8010/api/v1/interviews/{interview_id}/notes

List notes for an interview

curl -X GET 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "field_name": "string",
      "text": "string",
      "category": "string",
      "author_id": "550e8400-e29b-41d4-a716-446655440000",
      "pinned": false,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "client_created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

interview_idstring<uuid>requiredpath

field_namestring | nullquery

Filter by field/question name

categorystring | nullquery

Filter by note category

Response

200OKFormService_NoteListResponse

Successful Response

Response fields application/json

itemsArray<FormService_NoteResponseDto>required

Show child attributes

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

field_namestring | null

Show child attributes

Any of

string

null

textstringrequired

categorystringrequired

author_idstring | null

Show child attributes

Any of

string<uuid>

null

pinnedbooleanfalse

created_atstring<date-time>required

updated_atstring<date-time>required

client_created_atstring | null

Show child attributes

Any of

string<date-time>

null

totalintegerrequired

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Create a note for an interview

POST

http://localhost:8010/api/v1/interviews/{interview_id}/notes

Create a note for an interview

curl -X POST 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "field_name": "string",
  "text": "string",
  "category": "general",
  "client_created_at": "2024-01-15T09:30:00Z"
}'

const body = `{
  "field_name": "string",
  "text": "string",
  "category": "general",
  "client_created_at": "2024-01-15T09:30:00Z"
}`;

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "field_name": "string",
  "text": "string",
  "category": "general",
  "client_created_at": "2024-01-15T09:30:00Z"
}'''

response = requests.post(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "field_name": "string",
  "text": "string",
  "category": "general",
  "client_created_at": "2024-01-15T09:30:00Z"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "field_name": "string",
  "text": "string",
  "category": "string",
  "author_id": "550e8400-e29b-41d4-a716-446655440000",
  "pinned": false,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "client_created_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

field_namestring | null

Show child attributes

Any of

string

null

textstringrequired

categorystringgeneral

client_created_atstring | null

Show child attributes

Any of

string<date-time>

null

Parameters

interview_idstring<uuid>requiredpath

Response

201CreatedFormService_NoteResponseDto

Successful Response

Response fields application/json

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

field_namestring | null

Show child attributes

Any of

string

null

textstringrequired

categorystringrequired

author_idstring | null

Show child attributes

Any of

string<uuid>

null

pinnedbooleanfalse

created_atstring<date-time>required

updated_atstring<date-time>required

client_created_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get a specific note

GET

http://localhost:8010/api/v1/interviews/{interview_id}/notes/{note_id}

Get a specific note

curl -X GET 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "field_name": "string",
  "text": "string",
  "category": "string",
  "author_id": "550e8400-e29b-41d4-a716-446655440000",
  "pinned": false,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "client_created_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

interview_idstring<uuid>requiredpath

note_idstring<uuid>requiredpath

Response

200OKFormService_NoteResponseDto

Successful Response

Response fields application/json

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

field_namestring | null

Show child attributes

Any of

string

null

textstringrequired

categorystringrequired

author_idstring | null

Show child attributes

Any of

string<uuid>

null

pinnedbooleanfalse

created_atstring<date-time>required

updated_atstring<date-time>required

client_created_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Update a note

PUT

http://localhost:8010/api/v1/interviews/{interview_id}/notes/{note_id}

Update a note

curl -X PUT 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "text": "string",
  "category": "string",
  "pinned": true,
  "field_name": "string"
}'

const body = `{
  "text": "string",
  "category": "string",
  "pinned": true,
  "field_name": "string"
}`;

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "text": "string",
  "category": "string",
  "pinned": true,
  "field_name": "string"
}'''

response = requests.put(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "text": "string",
  "category": "string",
  "pinned": true,
  "field_name": "string"
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "field_name": "string",
  "text": "string",
  "category": "string",
  "author_id": "550e8400-e29b-41d4-a716-446655440000",
  "pinned": false,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "client_created_at": "2024-01-15T09:30:00Z"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

textstring | null

Show child attributes

Any of

string

null

categorystring | null

Show child attributes

Any of

string

null

pinnedboolean | null

Show child attributes

Any of

boolean

null

field_namestring | null

Show child attributes

Any of

string

null

Parameters

interview_idstring<uuid>requiredpath

note_idstring<uuid>requiredpath

Response

200OKFormService_NoteResponseDto

Successful Response

Response fields application/json

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

field_namestring | null

Show child attributes

Any of

string

null

textstringrequired

categorystringrequired

author_idstring | null

Show child attributes

Any of

string<uuid>

null

pinnedbooleanfalse

created_atstring<date-time>required

updated_atstring<date-time>required

client_created_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Delete a note

DELETE

http://localhost:8010/api/v1/interviews/{interview_id}/notes/{note_id}

Delete a note

curl -X DELETE 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

interview_idstring<uuid>requiredpath

note_idstring<uuid>requiredpath

Response

204No Content

Successful Response

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Batch create notes

POST

http://localhost:8010/api/v1/interviews/{interview_id}/notes/batch

Batch create notes

curl -X POST 'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "notes": [
    {
      "field_name": "string",
      "text": "string",
      "category": "general",
      "client_created_at": "2024-01-15T09:30:00Z"
    }
  ]
}'

const body = `{
  "notes": [
    {
      "field_name": "string",
      "text": "string",
      "category": "general",
      "client_created_at": "2024-01-15T09:30:00Z"
    }
  ]
}`;

const response = await fetch('http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "notes": [
    {
      "field_name": "string",
      "text": "string",
      "category": "general",
      "client_created_at": "2024-01-15T09:30:00Z"
    }
  ]
}'''

response = requests.post(
    'http://localhost:8010/api/v1/interviews/550e8400-e29b-41d4-a716-446655440000/notes/batch',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "notes": [
    {
      "field_name": "string",
      "text": "string",
      "category": "general",
      "client_created_at": "2024-01-15T09:30:00Z"
    }
  ]
}

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "interview_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
    "field_name": "string",
    "text": "string",
    "category": "string",
    "author_id": "550e8400-e29b-41d4-a716-446655440000",
    "pinned": false,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z",
    "client_created_at": "2024-01-15T09:30:00Z"
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

notesArray<FormService_NoteCreateDto>required

Show child attributes

field_namestring | null

Show child attributes

Any of

string

null

textstringrequired

categorystringgeneral

client_created_atstring | null

Show child attributes

Any of

string<date-time>

null

Parameters

interview_idstring<uuid>requiredpath

Response

201CreatedArray<FormService_NoteResponseDto>

Successful Response

Response fields application/json

Array<FormService_NoteResponseDto>

Show child attributes

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

field_namestring | null

Show child attributes

Any of

string

null

textstringrequired

categorystringrequired

author_idstring | null

Show child attributes

Any of

string<uuid>

null

pinnedbooleanfalse

created_atstring<date-time>required

updated_atstring<date-time>required

client_created_atstring | null

Show child attributes

Any of

string<date-time>

null

422Unprocessable EntityFormService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Media Service

Media upload, download, library, storage usage

Media Service / Health

Health — Media Service

Media Service / Upload

Upload — Media Service

Upload File

POST

http://localhost:8011/api/v1/media/upload

Upload a single file.

Args: file: The file to upload survey_id: Optional survey to associate with response_id: Optional response to associate with is_public: Whether the file is publicly accessible description: Optional file description survey_name: Optional survey name for custom renaming question_name: Optional question name for custom renaming user_name: Optional name of the user uploading the file checksum: Optional expected SHA-256 digest

Returns: Asset metadata including ID, filename, size, and type

Upload File

curl -X POST 'http://localhost:8011/api/v1/media/upload' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'file=string' \
  --form-string 'survey_id=string' \
  --form-string 'response_id=string' \
  --form-string 'entity_type=string' \
  --form-string 'entity_id=string' \
  --form-string 'is_public=false' \
  --form-string 'description=string' \
  --form-string 'survey_name=string' \
  --form-string 'question_name=string' \
  --form-string 'user_name=string' \
  --form-string 'device_id=string' \
  --form-string 'checksum=string'

const form = new FormData();
form.append('file', 'string');
form.append('survey_id', 'string');
form.append('response_id', 'string');
form.append('entity_type', 'string');
form.append('entity_id', 'string');
form.append('is_public', 'false');
form.append('description', 'string');
form.append('survey_name', 'string');
form.append('question_name', 'string');
form.append('user_name', 'string');
form.append('device_id', 'string');
form.append('checksum', 'string');
const response = await fetch('http://localhost:8011/api/v1/media/upload', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('file', (None, 'string')),
        ('survey_id', (None, 'string')),
        ('response_id', (None, 'string')),
        ('entity_type', (None, 'string')),
        ('entity_id', (None, 'string')),
        ('is_public', (None, 'false')),
        ('description', (None, 'string')),
        ('survey_name', (None, 'string')),
        ('question_name', (None, 'string')),
        ('user_name', (None, 'string')),
        ('device_id', (None, 'string')),
        ('checksum', (None, 'string')),
    ]
    response = requests.request('POST', 'http://localhost:8011/api/v1/media/upload', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "file": "string",
  "survey_id": "string",
  "response_id": "string",
  "entity_type": "string",
  "entity_id": "string",
  "is_public": false,
  "description": "string",
  "survey_name": "string",
  "question_name": "string",
  "user_name": "string",
  "device_id": "string",
  "checksum": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filestringrequired

survey_idstring | null

Show child attributes

Any of

string

null

response_idstring | null

Show child attributes

Any of

string

null

entity_typestring | null

Show child attributes

Any of

string

null

entity_idstring | null

Show child attributes

Any of

string

null

is_publicbooleanfalse

descriptionstring | null

Show child attributes

Any of

string

null

survey_namestring | null

Show child attributes

Any of

string

null

question_namestring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

device_idstring | null

Device that recorded this media (used for post-closure grant validation)

Show child attributes

Any of

string

null

checksumstring | null

Expected SHA-256 checksum of file

Show child attributes

Any of

string

null

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Upload Batch

POST

http://localhost:8011/api/v1/media/upload/batch

Upload multiple files at once.

Args: files: List of files to upload survey_id: Optional survey to associate with response_id: Optional response to associate with user_name: Optional name of the user uploading the files

Returns: Summary of uploaded files and any errors

Upload Batch

curl -X POST 'http://localhost:8011/api/v1/media/upload/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'files=string' \
  --form-string 'survey_id=string' \
  --form-string 'response_id=string' \
  --form-string 'entity_type=string' \
  --form-string 'entity_id=string' \
  --form-string 'user_name=string' \
  --form-string 'device_id=string'

const form = new FormData();
form.append('files', 'string');
form.append('survey_id', 'string');
form.append('response_id', 'string');
form.append('entity_type', 'string');
form.append('entity_id', 'string');
form.append('user_name', 'string');
form.append('device_id', 'string');
const response = await fetch('http://localhost:8011/api/v1/media/upload/batch', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('files', (None, 'string')),
        ('survey_id', (None, 'string')),
        ('response_id', (None, 'string')),
        ('entity_type', (None, 'string')),
        ('entity_id', (None, 'string')),
        ('user_name', (None, 'string')),
        ('device_id', (None, 'string')),
    ]
    response = requests.request('POST', 'http://localhost:8011/api/v1/media/upload/batch', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "files": [
    "string"
  ],
  "survey_id": "string",
  "response_id": "string",
  "entity_type": "string",
  "entity_id": "string",
  "user_name": "string",
  "device_id": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filesArray<string>required

survey_idstring | null

Show child attributes

Any of

string

null

response_idstring | null

Show child attributes

Any of

string

null

entity_typestring | null

Show child attributes

Any of

string

null

entity_idstring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

device_idstring | null

Device that recorded this media (used for post-closure grant validation)

Show child attributes

Any of

string

null

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Upload Chunk

POST

http://localhost:8011/api/v1/media/upload/chunk

Upload a single chunk of a large media file.

Mobile uploads files in 512KB chunks, posting each to this endpoint with the same upload_id. Chunks are staged on disk; when the final chunk (chunk_index == total_chunks - 1) arrives the full file is reassembled and stored via the standard media pipeline (compression, checksum, DB record).

survey_id is REQUIRED for production-bound uploads (project lifecycle gate; §5 row 11).
response_id is client-local at upload time and is never the enforcement key.
checksum (full-file SHA-256) is verified on the last chunk.

Upload Chunk

curl -X POST 'http://localhost:8011/api/v1/media/upload/chunk' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'file=string' \
  --form-string 'upload_id=string' \
  --form-string 'chunk_index=0' \
  --form-string 'total_chunks=1' \
  --form-string 'file_name=string' \
  --form-string 'mime_type=string' \
  --form-string 'survey_id=string' \
  --form-string 'response_id=string' \
  --form-string 'checksum=string' \
  --form-string 'device_id=string'

const form = new FormData();
form.append('file', 'string');
form.append('upload_id', 'string');
form.append('chunk_index', '0');
form.append('total_chunks', '1');
form.append('file_name', 'string');
form.append('mime_type', 'string');
form.append('survey_id', 'string');
form.append('response_id', 'string');
form.append('checksum', 'string');
form.append('device_id', 'string');
const response = await fetch('http://localhost:8011/api/v1/media/upload/chunk', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('file', (None, 'string')),
        ('upload_id', (None, 'string')),
        ('chunk_index', (None, '0')),
        ('total_chunks', (None, '1')),
        ('file_name', (None, 'string')),
        ('mime_type', (None, 'string')),
        ('survey_id', (None, 'string')),
        ('response_id', (None, 'string')),
        ('checksum', (None, 'string')),
        ('device_id', (None, 'string')),
    ]
    response = requests.request('POST', 'http://localhost:8011/api/v1/media/upload/chunk', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "file": "string",
  "upload_id": "string",
  "chunk_index": 0,
  "total_chunks": 1,
  "file_name": "string",
  "mime_type": "string",
  "survey_id": "string",
  "response_id": "string",
  "checksum": "string",
  "device_id": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filestringrequired

upload_idstringrequired

Client-generated stable upload ID (media local ID)

chunk_indexinteger>= 0required

Zero-based chunk index

total_chunksinteger[1, 100000]required

Total number of chunks

file_namestringrequired

mime_typestringrequired

survey_idstring | null

Survey this media belongs to (REQUIRED for production-bound uploads)

Show child attributes

Any of

string

null

response_idstring | null

Client-local response reference (metadata only — never the enforcement key)

Show child attributes

Any of

string

null

checksumstring | null

Expected SHA-256 of the FULL assembled file

Show child attributes

Any of

string

null

device_idstring | null

Device that recorded this media (used for post-closure grant validation)

Show child attributes

Any of

string

null

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Media Service / Download

Download — Media Service

Download File

GET

http://localhost:8011/api/v1/media/download/{asset_id}

Download a file by asset ID.

Download File

curl -X GET 'http://localhost:8011/api/v1/media/download/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/download/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/download/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

asset_idstringrequiredpath

tokenstring | nullquery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Stream File

GET

http://localhost:8011/api/v1/media/stream/{asset_id}

Stream a file inline (for images, audio, video).

Stream File

curl -X GET 'http://localhost:8011/api/v1/media/stream/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/stream/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/stream/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

asset_idstringrequiredpath

tokenstring | nullquery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Stream Thumbnail

GET

http://localhost:8011/api/v1/media/stream/{asset_id}/thumbnail

Stream an asset's thumbnail.

Stream Thumbnail

curl -X GET 'http://localhost:8011/api/v1/media/stream/string/thumbnail' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/stream/string/thumbnail', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/stream/string/thumbnail',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

asset_idstringrequiredpath

tokenstring | nullquery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get File By Name

GET

http://localhost:8011/api/v1/media/file/{filename}

Get a library file by its original filename. Used by form filler to display media files.

Get File By Name

curl -X GET 'http://localhost:8011/api/v1/media/file/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/file/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/file/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

filenamestringrequiredpath

tokenstring | nullquery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Media Service / Assets

Assets — Media Service

List Assets

GET

http://localhost:8011/api/v1/media/assets

List media assets with optional filters.

List Assets

curl -X GET 'http://localhost:8011/api/v1/media/assets?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/assets?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/assets?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

survey_idstring | nullquery

response_idstring | nullquery

entity_typestring | nullquery

entity_idstring | nullquery

asset_typestring | nullquery

skipinteger0query

limitinteger20query

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get Asset

GET

http://localhost:8011/api/v1/media/assets/{asset_id}

Get asset metadata.

Get Asset

curl -X GET 'http://localhost:8011/api/v1/media/assets/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/assets/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/assets/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

asset_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Update Asset

PUT

http://localhost:8011/api/v1/media/assets/{asset_id}

Update asset metadata.

Update Asset

curl -X PUT 'http://localhost:8011/api/v1/media/assets/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "original_filename": "string",
  "description": "string",
  "alt_text": "string",
  "tags": [
    "string"
  ],
  "is_public": true
}'

const body = `{
  "original_filename": "string",
  "description": "string",
  "alt_text": "string",
  "tags": [
    "string"
  ],
  "is_public": true
}`;

const response = await fetch('http://localhost:8011/api/v1/media/assets/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "original_filename": "string",
  "description": "string",
  "alt_text": "string",
  "tags": [
    "string"
  ],
  "is_public": true
}'''

response = requests.put(
    'http://localhost:8011/api/v1/media/assets/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "original_filename": "string",
  "description": "string",
  "alt_text": "string",
  "tags": [
    "string"
  ],
  "is_public": true
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

original_filenamestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

alt_textstring | null

Show child attributes

Any of

string

null

tagsArray<string> | null

Show child attributes

Any of

Array<string>

null

is_publicboolean | null

Show child attributes

Any of

boolean

null

Parameters

asset_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Delete Asset

DELETE

http://localhost:8011/api/v1/media/assets/{asset_id}

Delete an asset and its stored files.

Delete Asset

curl -X DELETE 'http://localhost:8011/api/v1/media/assets/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/assets/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8011/api/v1/media/assets/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

asset_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get Presigned Url

GET

http://localhost:8011/api/v1/media/assets/{asset_id}/presigned

Get a proxy URL for direct file access.

Get Presigned Url

curl -X GET 'http://localhost:8011/api/v1/media/assets/string/presigned?expires_in=3600' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/assets/string/presigned?expires_in=3600', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/assets/string/presigned?expires_in=3600',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

asset_idstringrequiredpath

expires_ininteger3600query

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Link Asset To Response

POST

http://localhost:8011/api/v1/media/assets/{asset_id}/link

Link an asset to a form response.

Link Asset To Response

curl -X POST 'http://localhost:8011/api/v1/media/assets/string/link' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'

const response = await fetch('http://localhost:8011/api/v1/media/assets/string/link', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body: '{}',
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8011/api/v1/media/assets/string/link',
    data='{}'.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

object

Parameters

asset_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get Assets For Response

GET

http://localhost:8011/api/v1/media/assets/by-response/{response_id}

Get all assets associated with a response.

Get Assets For Response

curl -X GET 'http://localhost:8011/api/v1/media/assets/by-response/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/assets/by-response/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/assets/by-response/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

response_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get Asset By Upload Id

GET

http://localhost:8011/api/v1/media/assets/by-upload/{upload_id}

Resolve a Media Track upload_id to its canonical MediaAsset.id.

This is the mobile half of the media identity map. A mobile answer carries asset_ref="upload_id" while offline, so the canonical server identity is reached through this endpoint rather than by assuming the client's id is a MediaAsset.id.

Deliberately narrow, to match the frozen contract: one indexed lookup on upload_id, tenant-scoped, at most one result. There is no fallback to a MediaAsset.id lookup, no question-name lookup, and no response-id lookup, so an unresolved reference stays unresolved instead of resolving to something it was not.

Get Asset By Upload Id

curl -X GET 'http://localhost:8011/api/v1/media/assets/by-upload/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/assets/by-upload/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/assets/by-upload/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

upload_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Media Service / Media Library

Media Library — Media Service

Upload Library File

POST

http://localhost:8011/api/v1/media/library/upload

Upload a file to the tenant's shared media library.

Uploaded files can then be referenced by filename in survey question and choice media_file fields.

Allowed types: images (jpg, png, gif, webp), audio (mp3, wav, ogg), video (mp4, webm).

Upload Library File

curl -X POST 'http://localhost:8011/api/v1/media/library/upload' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'file=string' \
  --form-string 'description=string' \
  --form-string 'survey_name=string' \
  --form-string 'question_name=string' \
  --form-string 'response_id=string'

const form = new FormData();
form.append('file', 'string');
form.append('description', 'string');
form.append('survey_name', 'string');
form.append('question_name', 'string');
form.append('response_id', 'string');
const response = await fetch('http://localhost:8011/api/v1/media/library/upload', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('file', (None, 'string')),
        ('description', (None, 'string')),
        ('survey_name', (None, 'string')),
        ('question_name', (None, 'string')),
        ('response_id', (None, 'string')),
    ]
    response = requests.request('POST', 'http://localhost:8011/api/v1/media/library/upload', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "file": "string",
  "description": "string",
  "survey_name": "string",
  "question_name": "string",
  "response_id": "string"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filestringrequired

Media file to add to the library

descriptionstring | null

Optional description

Show child attributes

Any of

string

null

survey_namestring | null

Optional survey name for renaming

Show child attributes

Any of

string

null

question_namestring | null

Optional question name for renaming

Show child attributes

Any of

string

null

response_idstring | null

Optional response ID for renaming

Show child attributes

Any of

string

null

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Upload Library Files Batch

POST

http://localhost:8011/api/v1/media/library/upload/batch

Upload multiple files to the tenant's media library at once.

Upload Library Files Batch

curl -X POST 'http://localhost:8011/api/v1/media/library/upload/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --form-string 'files=string'

const form = new FormData();
form.append('files', 'string');
const response = await fetch('http://localhost:8011/api/v1/media/library/upload/batch', {
  method: 'POST',
  headers: {"Authorization":"Bearer YOUR_TOKEN"},
  body: form,
});
console.log(await response.text());

import requests
from contextlib import ExitStack

with ExitStack() as stack:
    files = [
        ('files', (None, 'string')),
    ]
    response = requests.request('POST', 'http://localhost:8011/api/v1/media/library/upload/batch', headers={"Authorization":"Bearer YOUR_TOKEN"}, files=files)
    print(response.text)

Request Body

{
  "files": [
    "string"
  ]
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

multipart/form-data

filesArray<string>required

Media files to add to the library

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

List Library

GET

http://localhost:8011/api/v1/media/library

List all files in the tenant's shared media library.

Supports filtering by asset_type (image, audio, video), filename search, and tags (comma-separated, returns assets with any matching tag).

List Library

curl -X GET 'http://localhost:8011/api/v1/media/library?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/library?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/library?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

asset_typestring | nullquery

Filter by type: image, audio, video

searchstring | nullquery

Search by filename

tagsstring | nullquery

Comma-separated tags to filter by (OR logic — assets with any matching tag)

skipinteger>= 00query

Row offset

limitinteger[1, 100]20query

Items per page

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get Library Asset By Filename

GET

http://localhost:8011/api/v1/media/library/by-filename/{filename}

Look up a library asset by its original filename.

Used by form-service during form rendering to resolve media_file values to actual stream URLs.

Get Library Asset By Filename

curl -X GET 'http://localhost:8011/api/v1/media/library/by-filename/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/library/by-filename/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/library/by-filename/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

filenamestringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get Library Asset Url

GET

http://localhost:8011/api/v1/media/library/{asset_id}/url

Get the stream URL for a library asset.

Returns the URL to stream/display the file inline.

Get Library Asset Url

curl -X GET 'http://localhost:8011/api/v1/media/library/string/url' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/library/string/url', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/library/string/url',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

asset_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Update Library Asset Status

PATCH

http://localhost:8011/api/v1/media/library/{asset_id}/status

Update a library asset's approval status (pending/approved/rejected).

Only users with the MEDIA_MANAGE permission can approve or reject media. Pending/rejected library assets are not usable in forms — the by-filename lookup, stream/download endpoints, and survey enrichment all block them.

Update Library Asset Status

curl -X PATCH 'http://localhost:8011/api/v1/media/library/string/status' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{}'

const response = await fetch('http://localhost:8011/api/v1/media/library/string/status', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body: '{}',
});

const data = await response.text();

import requests

response = requests.patch(
    'http://localhost:8011/api/v1/media/library/string/status',
    data='{}'.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

object

Parameters

asset_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Delete Library Asset

DELETE

http://localhost:8011/api/v1/media/library/{asset_id}

Delete a file from the tenant's media library.

Warning: This will remove the file from storage. Any surveys that reference this file by name will no longer be able to display it.

Delete Library Asset

curl -X DELETE 'http://localhost:8011/api/v1/media/library/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/library/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8011/api/v1/media/library/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

asset_idstringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityMediaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Media Service / Storage Usage

Storage Usage — Media Service

Get Storage Usage

GET

http://localhost:8011/api/v1/media/storage/usage

Get Storage Usage

curl -X GET 'http://localhost:8011/api/v1/media/storage/usage' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8011/api/v1/media/storage/usage', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8011/api/v1/media/storage/usage',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Authorization

HTTPBearerhttp (bearer)

Notification Service

Notification templates, sending, preferences, history

Notification Service / Health

Health — Notification Service

Notification Service / Send

Send — Notification Service

Send Notification

POST

http://localhost:8012/api/v1/notification/send

Send Notification

curl -X POST 'http://localhost:8012/api/v1/notification/send' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "channel": "email",
  "recipient": "string",
  "subject": "string",
  "body": "string",
  "template_id": "string",
  "template_vars": {},
  "user_id": "string",
  "notification_type": "account_activation",
  "metadata": {}
}'

const body = `{
  "channel": "email",
  "recipient": "string",
  "subject": "string",
  "body": "string",
  "template_id": "string",
  "template_vars": {},
  "user_id": "string",
  "notification_type": "account_activation",
  "metadata": {}
}`;

const response = await fetch('http://localhost:8012/api/v1/notification/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "channel": "email",
  "recipient": "string",
  "subject": "string",
  "body": "string",
  "template_id": "string",
  "template_vars": {},
  "user_id": "string",
  "notification_type": "account_activation",
  "metadata": {}
}'''

response = requests.post(
    'http://localhost:8012/api/v1/notification/send',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "channel": "email",
  "recipient": "string",
  "subject": "string",
  "body": "string",
  "template_id": "string",
  "template_vars": {},
  "user_id": "string",
  "notification_type": "account_activation",
  "metadata": {}
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

channelstringemailsmsslackrequired

recipientstringrequired

subjectstring | null

Show child attributes

Any of

string

null

bodystringrequired

template_idstring | null

Show child attributes

Any of

string

null

template_varsobject | null

Show child attributes

Any of

object

null

user_idstring | null

Show child attributes

Any of

string

null

notification_typeNotificationService_NotificationType | string | null

Show child attributes

Any of

NotificationService_NotificationTypeaccount_activationpassword_reset_requestpassword_changedemail_change_confirmationemail_changed_notifymagic_link_loginaudit_security_alertdns_notificationwelcome_emailtenant_activedownload_readymedia_export_ready

string

null

metadataobject | null

Show child attributes

Any of

object

null

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Send Batch

POST

http://localhost:8012/api/v1/notification/send/batch

Send Batch

curl -X POST 'http://localhost:8012/api/v1/notification/send/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "notifications": [
    {
      "channel": "email",
      "recipient": "string",
      "subject": "string",
      "body": "string",
      "template_id": "string",
      "template_vars": {},
      "user_id": "string",
      "notification_type": "account_activation",
      "metadata": {}
    }
  ]
}'

const body = `{
  "notifications": [
    {
      "channel": "email",
      "recipient": "string",
      "subject": "string",
      "body": "string",
      "template_id": "string",
      "template_vars": {},
      "user_id": "string",
      "notification_type": "account_activation",
      "metadata": {}
    }
  ]
}`;

const response = await fetch('http://localhost:8012/api/v1/notification/send/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "notifications": [
    {
      "channel": "email",
      "recipient": "string",
      "subject": "string",
      "body": "string",
      "template_id": "string",
      "template_vars": {},
      "user_id": "string",
      "notification_type": "account_activation",
      "metadata": {}
    }
  ]
}'''

response = requests.post(
    'http://localhost:8012/api/v1/notification/send/batch',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "notifications": [
    {
      "channel": "email",
      "recipient": "string",
      "subject": "string",
      "body": "string",
      "template_id": "string",
      "template_vars": {},
      "user_id": "string",
      "notification_type": "account_activation",
      "metadata": {}
    }
  ]
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

notificationsArray<NotificationService_SendNotificationRequest>required

Show child attributes

channelstringemailsmsslackrequired

recipientstringrequired

subjectstring | null

Show child attributes

Any of

string

null

bodystringrequired

template_idstring | null

Show child attributes

Any of

string

null

template_varsobject | null

Show child attributes

Any of

object

null

user_idstring | null

Show child attributes

Any of

string

null

notification_typeNotificationService_NotificationType | string | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

Response

202Acceptedany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Notification Service / Templates

Templates — Notification Service

List Templates

GET

http://localhost:8012/api/v1/notification/templates

List Templates

curl -X GET 'http://localhost:8012/api/v1/notification/templates' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8012/api/v1/notification/templates', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8012/api/v1/notification/templates',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

channelstring | nullquery

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Create Template

POST

http://localhost:8012/api/v1/notification/templates

Create Template

curl -X POST 'http://localhost:8012/api/v1/notification/templates' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "channel": "string",
  "subject_template": "string",
  "body_template": "string",
  "variables": [
    "string"
  ]
}'

const body = `{
  "name": "string",
  "channel": "string",
  "subject_template": "string",
  "body_template": "string",
  "variables": [
    "string"
  ]
}`;

const response = await fetch('http://localhost:8012/api/v1/notification/templates', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "channel": "string",
  "subject_template": "string",
  "body_template": "string",
  "variables": [
    "string"
  ]
}'''

response = requests.post(
    'http://localhost:8012/api/v1/notification/templates',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "channel": "string",
  "subject_template": "string",
  "body_template": "string",
  "variables": [
    "string"
  ]
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestringrequired

channelstringrequired

subject_templatestring | null

Show child attributes

Any of

string

null

body_templatestringrequired

variablesArray<string> | null

Show child attributes

Any of

Array<string>

null

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Preview Template Live

POST

http://localhost:8012/api/v1/notification/templates/preview

Preview Template Live

curl -X POST 'http://localhost:8012/api/v1/notification/templates/preview' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "subject_template": "string",
  "body_template": "string",
  "variables": {}
}'

const body = `{
  "subject_template": "string",
  "body_template": "string",
  "variables": {}
}`;

const response = await fetch('http://localhost:8012/api/v1/notification/templates/preview', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "subject_template": "string",
  "body_template": "string",
  "variables": {}
}'''

response = requests.post(
    'http://localhost:8012/api/v1/notification/templates/preview',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "subject_template": "string",
  "body_template": "string",
  "variables": {}
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

subject_templatestring | null

Show child attributes

Any of

string

null

body_templatestringrequired

variablesobject[object Object]

Show child attributes

[key: string]string

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get Template

GET

http://localhost:8012/api/v1/notification/templates/{template_id}

Get Template

curl -X GET 'http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

template_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Update Template

PUT

http://localhost:8012/api/v1/notification/templates/{template_id}

Update Template

curl -X PUT 'http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "subject_template": "string",
  "body_template": "string",
  "variables": [
    "string"
  ],
  "is_active": true
}'

const body = `{
  "name": "string",
  "subject_template": "string",
  "body_template": "string",
  "variables": [
    "string"
  ],
  "is_active": true
}`;

const response = await fetch('http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "subject_template": "string",
  "body_template": "string",
  "variables": [
    "string"
  ],
  "is_active": true
}'''

response = requests.put(
    'http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "subject_template": "string",
  "body_template": "string",
  "variables": [
    "string"
  ],
  "is_active": true
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestring | null

Show child attributes

Any of

string

null

subject_templatestring | null

Show child attributes

Any of

string

null

body_templatestring | null

Show child attributes

Any of

string

null

variablesArray<string> | null

Show child attributes

Any of

Array<string>

null

is_activeboolean | null

Show child attributes

Any of

boolean

null

Parameters

template_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Delete Template

DELETE

http://localhost:8012/api/v1/notification/templates/{template_id}

Delete Template

curl -X DELETE 'http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

template_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Preview Template

POST

http://localhost:8012/api/v1/notification/templates/{template_id}/preview

Preview Template

curl -X POST 'http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000/preview' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "variables": {}
}'

const body = `{
  "variables": {}
}`;

const response = await fetch('http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000/preview', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "variables": {}
}'''

response = requests.post(
    'http://localhost:8012/api/v1/notification/templates/550e8400-e29b-41d4-a716-446655440000/preview',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "variables": {}
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

variablesobject[object Object]

Show child attributes

[key: string]string

Parameters

template_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Notification Service / Preferences

Preferences — Notification Service

Get Preferences

GET

http://localhost:8012/api/v1/notification/preferences

Get Preferences

curl -X GET 'http://localhost:8012/api/v1/notification/preferences' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8012/api/v1/notification/preferences', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8012/api/v1/notification/preferences',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Authorization

HTTPBearerhttp (bearer)

Set Preference

POST

http://localhost:8012/api/v1/notification/preferences

Set Preference

curl -X POST 'http://localhost:8012/api/v1/notification/preferences' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "channel": "string",
  "is_enabled": true,
  "quiet_hours_start": "string",
  "quiet_hours_end": "string",
  "frequency": "immediate"
}'

const body = `{
  "channel": "string",
  "is_enabled": true,
  "quiet_hours_start": "string",
  "quiet_hours_end": "string",
  "frequency": "immediate"
}`;

const response = await fetch('http://localhost:8012/api/v1/notification/preferences', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "channel": "string",
  "is_enabled": true,
  "quiet_hours_start": "string",
  "quiet_hours_end": "string",
  "frequency": "immediate"
}'''

response = requests.post(
    'http://localhost:8012/api/v1/notification/preferences',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "channel": "string",
  "is_enabled": true,
  "quiet_hours_start": "string",
  "quiet_hours_end": "string",
  "frequency": "immediate"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

channelstringrequired

is_enabledbooleantrue

quiet_hours_startstring | null

Show child attributes

Any of

string

null

quiet_hours_endstring | null

Show child attributes

Any of

string

null

frequencystringimmediate

Response

201Createdany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Update Preference

PUT

http://localhost:8012/api/v1/notification/preferences/{pref_id}

Update Preference

curl -X PUT 'http://localhost:8012/api/v1/notification/preferences/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "channel": "string",
  "is_enabled": true,
  "quiet_hours_start": "string",
  "quiet_hours_end": "string",
  "frequency": "immediate"
}'

const body = `{
  "channel": "string",
  "is_enabled": true,
  "quiet_hours_start": "string",
  "quiet_hours_end": "string",
  "frequency": "immediate"
}`;

const response = await fetch('http://localhost:8012/api/v1/notification/preferences/550e8400-e29b-41d4-a716-446655440000', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "channel": "string",
  "is_enabled": true,
  "quiet_hours_start": "string",
  "quiet_hours_end": "string",
  "frequency": "immediate"
}'''

response = requests.put(
    'http://localhost:8012/api/v1/notification/preferences/550e8400-e29b-41d4-a716-446655440000',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "channel": "string",
  "is_enabled": true,
  "quiet_hours_start": "string",
  "quiet_hours_end": "string",
  "frequency": "immediate"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

channelstringrequired

is_enabledbooleantrue

quiet_hours_startstring | null

Show child attributes

Any of

string

null

quiet_hours_endstring | null

Show child attributes

Any of

string

null

frequencystringimmediate

Parameters

pref_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Delete Preference

DELETE

http://localhost:8012/api/v1/notification/preferences/{pref_id}

Delete Preference

curl -X DELETE 'http://localhost:8012/api/v1/notification/preferences/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8012/api/v1/notification/preferences/550e8400-e29b-41d4-a716-446655440000', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8012/api/v1/notification/preferences/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

pref_idstring<uuid>requiredpath

Response

204No Content

Successful Response

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Notification Service / Settings

Settings — Notification Service

Get Settings

GET

http://localhost:8012/api/v1/notification/settings

Get Settings

curl -X GET 'http://localhost:8012/api/v1/notification/settings' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8012/api/v1/notification/settings', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8012/api/v1/notification/settings',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

200

{
  "sms_provider": "string",
  "smtp": {
    "smtp_host": "string",
    "smtp_port": 0,
    "smtp_username": "string",
    "smtp_password": "••••••••",
    "smtp_from_email": "string",
    "smtp_from_name": "string",
    "smtp_use_tls": true
  },
  "aws": {
    "aws_region": "string",
    "aws_access_key_id": "••••••••",
    "aws_secret_access_key": "••••••••",
    "aws_origination_number": "string"
  },
  "twilio": {
    "twilio_account_sid": "string",
    "twilio_auth_token": "••••••••",
    "twilio_from_number": "string"
  },
  "msg91": {
    "msg91_api_key": "••••••••",
    "msg91_sender_id": "string",
    "msg91_flow_id": "string",
    "msg91_route": "string"
  },
  "kaleyra": {
    "kaleyra_api_key": "••••••••",
    "kaleyra_account_sid": "string",
    "kaleyra_sender_id": "string"
  },
  "africas_talking": {
    "africas_talking_username": "string",
    "africas_talking_api_key": "••••••••",
    "africas_talking_shortcode": "string"
  },
  "generic_http": {
    "generic_sms_endpoint": "string",
    "generic_sms_method": "string",
    "generic_sms_auth_header_name": "string",
    "generic_sms_auth_header_value": "••••••••",
    "generic_sms_body_template": "string"
  },
  "slack": {
    "slack_webhook_url": "••••••••"
  },
  "is_active": true,
  "created_at": "string",
  "updated_at": "string"
}

Response

200OKNotificationService_NotificationSettingsResponse

Successful Response

Response fields application/json

sms_providerstringrequired

smtpNotificationService_SMTPConfigResponserequired

Show child attributes

smtp_hoststring | null

Show child attributes

Any of

string

null

smtp_portinteger | null

Show child attributes

Any of

integer

null

smtp_usernamestring | null

Show child attributes

Any of

string

null

smtp_passwordstring | null••••••••

Show child attributes

Any of

string

null

smtp_from_emailstring | null

Show child attributes

Any of

string

null

smtp_from_namestring | null

Show child attributes

Any of

string

null

smtp_use_tlsboolean | null

Show child attributes

Any of

boolean

null

awsNotificationService_AWSConfigResponse | null

Show child attributes

Any of

aws_regionstring | null

Show child attributes

Any of

string

null

aws_access_key_idstring | null••••••••

Show child attributes

Any of

string

null

aws_secret_access_keystring | null••••••••

Show child attributes

Any of

string

null

aws_origination_numberstring | null

Show child attributes

Any of

string

null

twilioNotificationService_TwilioConfigResponse | null

Show child attributes

Any of

twilio_account_sidstring | null

Show child attributes

Any of

string

null

twilio_auth_tokenstring | null••••••••

Show child attributes

Any of

string

null

twilio_from_numberstring | null

Show child attributes

Any of

string

null

msg91NotificationService_MSG91ConfigResponse | null

Show child attributes

Any of

msg91_api_keystring | null••••••••

Show child attributes

Any of

string

null

msg91_sender_idstring | null

Show child attributes

Any of

string

null

msg91_flow_idstring | null

Show child attributes

Any of

string

null

msg91_routestring | null

Show child attributes

Any of

string

null

kaleyraNotificationService_KaleyraConfigResponse | null

Show child attributes

Any of

kaleyra_api_keystring | null••••••••

Show child attributes

Any of

string

null

kaleyra_account_sidstring | null

Show child attributes

Any of

string

null

kaleyra_sender_idstring | null

Show child attributes

Any of

string

null

africas_talkingNotificationService_AfricasTalkingConfigResponse | null

Show child attributes

Any of

africas_talking_usernamestring | null

Show child attributes

Any of

string

null

africas_talking_api_keystring | null••••••••

Show child attributes

Any of

string

null

africas_talking_shortcodestring | null

Show child attributes

Any of

string

null

generic_httpNotificationService_GenericHttpConfigResponse | null

Show child attributes

Any of

generic_sms_endpointstring | null

Show child attributes

Any of

string

null

generic_sms_methodstring | null

Show child attributes

Any of

string

null

generic_sms_auth_header_namestring | null

Show child attributes

Any of

string

null

generic_sms_auth_header_valuestring | null••••••••

Show child attributes

Any of

string

null

generic_sms_body_templatestring | null

Show child attributes

Any of

string

null

slackNotificationService_SlackConfigResponse | null

Show child attributes

Any of

slack_webhook_urlstring | null••••••••

Show child attributes

Any of

string

null

is_activebooleanrequired

created_atstringrequired

updated_atstringrequired

Authorization

HTTPBearerhttp (bearer)

Update Settings

PUT

http://localhost:8012/api/v1/notification/settings

Update Settings

curl -X PUT 'http://localhost:8012/api/v1/notification/settings' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "smtp": {
    "smtp_host": "string",
    "smtp_port": 587,
    "smtp_username": "string",
    "smtp_password": "string",
    "smtp_from_email": "string",
    "smtp_from_name": "string",
    "smtp_use_tls": true
  },
  "sms_provider": "mock",
  "aws": {
    "aws_region": "string",
    "aws_access_key_id": "string",
    "aws_secret_access_key": "string",
    "aws_origination_number": "string"
  },
  "twilio": {
    "twilio_account_sid": "string",
    "twilio_auth_token": "string",
    "twilio_from_number": "string"
  },
  "msg91": {
    "msg91_api_key": "string",
    "msg91_sender_id": "string",
    "msg91_flow_id": "string",
    "msg91_route": "4"
  },
  "kaleyra": {
    "kaleyra_api_key": "string",
    "kaleyra_account_sid": "string",
    "kaleyra_sender_id": "string"
  },
  "africas_talking": {
    "africas_talking_username": "string",
    "africas_talking_api_key": "string",
    "africas_talking_shortcode": "string"
  },
  "generic_http": {
    "generic_sms_endpoint": "string",
    "generic_sms_method": "POST",
    "generic_sms_auth_header_name": "string",
    "generic_sms_auth_header_value": "string",
    "generic_sms_body_template": "string"
  },
  "slack": {
    "slack_webhook_url": "string"
  }
}'

const body = `{
  "smtp": {
    "smtp_host": "string",
    "smtp_port": 587,
    "smtp_username": "string",
    "smtp_password": "string",
    "smtp_from_email": "string",
    "smtp_from_name": "string",
    "smtp_use_tls": true
  },
  "sms_provider": "mock",
  "aws": {
    "aws_region": "string",
    "aws_access_key_id": "string",
    "aws_secret_access_key": "string",
    "aws_origination_number": "string"
  },
  "twilio": {
    "twilio_account_sid": "string",
    "twilio_auth_token": "string",
    "twilio_from_number": "string"
  },
  "msg91": {
    "msg91_api_key": "string",
    "msg91_sender_id": "string",
    "msg91_flow_id": "string",
    "msg91_route": "4"
  },
  "kaleyra": {
    "kaleyra_api_key": "string",
    "kaleyra_account_sid": "string",
    "kaleyra_sender_id": "string"
  },
  "africas_talking": {
    "africas_talking_username": "string",
    "africas_talking_api_key": "string",
    "africas_talking_shortcode": "string"
  },
  "generic_http": {
    "generic_sms_endpoint": "string",
    "generic_sms_method": "POST",
    "generic_sms_auth_header_name": "string",
    "generic_sms_auth_header_value": "string",
    "generic_sms_body_template": "string"
  },
  "slack": {
    "slack_webhook_url": "string"
  }
}`;

const response = await fetch('http://localhost:8012/api/v1/notification/settings', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "smtp": {
    "smtp_host": "string",
    "smtp_port": 587,
    "smtp_username": "string",
    "smtp_password": "string",
    "smtp_from_email": "string",
    "smtp_from_name": "string",
    "smtp_use_tls": true
  },
  "sms_provider": "mock",
  "aws": {
    "aws_region": "string",
    "aws_access_key_id": "string",
    "aws_secret_access_key": "string",
    "aws_origination_number": "string"
  },
  "twilio": {
    "twilio_account_sid": "string",
    "twilio_auth_token": "string",
    "twilio_from_number": "string"
  },
  "msg91": {
    "msg91_api_key": "string",
    "msg91_sender_id": "string",
    "msg91_flow_id": "string",
    "msg91_route": "4"
  },
  "kaleyra": {
    "kaleyra_api_key": "string",
    "kaleyra_account_sid": "string",
    "kaleyra_sender_id": "string"
  },
  "africas_talking": {
    "africas_talking_username": "string",
    "africas_talking_api_key": "string",
    "africas_talking_shortcode": "string"
  },
  "generic_http": {
    "generic_sms_endpoint": "string",
    "generic_sms_method": "POST",
    "generic_sms_auth_header_name": "string",
    "generic_sms_auth_header_value": "string",
    "generic_sms_body_template": "string"
  },
  "slack": {
    "slack_webhook_url": "string"
  }
}'''

response = requests.put(
    'http://localhost:8012/api/v1/notification/settings',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "smtp": {
    "smtp_host": "string",
    "smtp_port": 587,
    "smtp_username": "string",
    "smtp_password": "string",
    "smtp_from_email": "string",
    "smtp_from_name": "string",
    "smtp_use_tls": true
  },
  "sms_provider": "mock",
  "aws": {
    "aws_region": "string",
    "aws_access_key_id": "string",
    "aws_secret_access_key": "string",
    "aws_origination_number": "string"
  },
  "twilio": {
    "twilio_account_sid": "string",
    "twilio_auth_token": "string",
    "twilio_from_number": "string"
  },
  "msg91": {
    "msg91_api_key": "string",
    "msg91_sender_id": "string",
    "msg91_flow_id": "string",
    "msg91_route": "4"
  },
  "kaleyra": {
    "kaleyra_api_key": "string",
    "kaleyra_account_sid": "string",
    "kaleyra_sender_id": "string"
  },
  "africas_talking": {
    "africas_talking_username": "string",
    "africas_talking_api_key": "string",
    "africas_talking_shortcode": "string"
  },
  "generic_http": {
    "generic_sms_endpoint": "string",
    "generic_sms_method": "POST",
    "generic_sms_auth_header_name": "string",
    "generic_sms_auth_header_value": "string",
    "generic_sms_body_template": "string"
  },
  "slack": {
    "slack_webhook_url": "string"
  }
}

{
  "sms_provider": "string",
  "smtp": {
    "smtp_host": "string",
    "smtp_port": 0,
    "smtp_username": "string",
    "smtp_password": "••••••••",
    "smtp_from_email": "string",
    "smtp_from_name": "string",
    "smtp_use_tls": true
  },
  "aws": {
    "aws_region": "string",
    "aws_access_key_id": "••••••••",
    "aws_secret_access_key": "••••••••",
    "aws_origination_number": "string"
  },
  "twilio": {
    "twilio_account_sid": "string",
    "twilio_auth_token": "••••••••",
    "twilio_from_number": "string"
  },
  "msg91": {
    "msg91_api_key": "••••••••",
    "msg91_sender_id": "string",
    "msg91_flow_id": "string",
    "msg91_route": "string"
  },
  "kaleyra": {
    "kaleyra_api_key": "••••••••",
    "kaleyra_account_sid": "string",
    "kaleyra_sender_id": "string"
  },
  "africas_talking": {
    "africas_talking_username": "string",
    "africas_talking_api_key": "••••••••",
    "africas_talking_shortcode": "string"
  },
  "generic_http": {
    "generic_sms_endpoint": "string",
    "generic_sms_method": "string",
    "generic_sms_auth_header_name": "string",
    "generic_sms_auth_header_value": "••••••••",
    "generic_sms_body_template": "string"
  },
  "slack": {
    "slack_webhook_url": "••••••••"
  },
  "is_active": true,
  "created_at": "string",
  "updated_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

smtpNotificationService_SMTPConfig | null

Show child attributes

Any of

smtp_hoststring | null

Show child attributes

Any of

string

null

smtp_portinteger | null587

Show child attributes

Any of

integer[1, 65535]

null

smtp_usernamestring | null

Show child attributes

Any of

string

null

smtp_passwordstring | null

Show child attributes

Any of

string

null

smtp_from_emailstring | null

Show child attributes

Any of

string

null

smtp_from_namestring | null

Show child attributes

Any of

string

null

smtp_use_tlsbooleantrue

null

sms_providerstringmockaws_end_user_messagingtwiliomsg91kaleyraafricas_talkinggeneric_httpmock

awsNotificationService_AWSConfig | null

Show child attributes

Any of

aws_regionstring | null

Show child attributes

Any of

string

null

aws_access_key_idstring | null

Show child attributes

Any of

string

null

aws_secret_access_keystring | null

Show child attributes

Any of

string

null

aws_origination_numberstring | null

Show child attributes

Any of

string

null

twilioNotificationService_TwilioConfig | null

Show child attributes

Any of

twilio_account_sidstring | null

Show child attributes

Any of

string

null

twilio_auth_tokenstring | null

Show child attributes

Any of

string

null

twilio_from_numberstring | null

Show child attributes

Any of

string

null

msg91NotificationService_MSG91Config | null

Show child attributes

Any of

msg91_api_keystring | null

Show child attributes

Any of

string

null

msg91_sender_idstring | null

Show child attributes

Any of

string

null

msg91_flow_idstring | null

Show child attributes

Any of

string

null

msg91_routestring144

null

kaleyraNotificationService_KaleyraConfig | null

Show child attributes

Any of

kaleyra_api_keystring | null

Show child attributes

Any of

string

null

kaleyra_account_sidstring | null

Show child attributes

Any of

string

null

kaleyra_sender_idstring | null

Show child attributes

Any of

string

null

africas_talkingNotificationService_AfricasTalkingConfig | null

Show child attributes

Any of

africas_talking_usernamestring | null

Show child attributes

Any of

string

null

africas_talking_api_keystring | null

Show child attributes

Any of

string

null

africas_talking_shortcodestring | null

Show child attributes

Any of

string

null

generic_httpNotificationService_GenericHttpConfig | null

Show child attributes

Any of

generic_sms_endpointstring | null

Show child attributes

Any of

string

null

generic_sms_methodstringPOSTGETPOST

generic_sms_auth_header_namestring | null

Show child attributes

Any of

string

null

generic_sms_auth_header_valuestring | null

Show child attributes

Any of

string

null

generic_sms_body_templatestring | null

Show child attributes

Any of

string

null

slackNotificationService_SlackConfig | null

Show child attributes

Any of

slack_webhook_urlstring | null

Show child attributes

Any of

string

null

Response

200OKNotificationService_NotificationSettingsResponse

Successful Response

Response fields application/json

sms_providerstringrequired

smtpNotificationService_SMTPConfigResponserequired

Show child attributes

smtp_hoststring | null

Show child attributes

Any of

string

null

smtp_portinteger | null

Show child attributes

Any of

integer

null

smtp_usernamestring | null

Show child attributes

Any of

string

null

smtp_passwordstring | null••••••••

Show child attributes

Any of

string

null

smtp_from_emailstring | null

Show child attributes

Any of

string

null

smtp_from_namestring | null

Show child attributes

Any of

string

null

smtp_use_tlsboolean | null

Show child attributes

Any of

boolean

null

awsNotificationService_AWSConfigResponse | null

Show child attributes

Any of

aws_regionstring | null

Show child attributes

Any of

string

null

aws_access_key_idstring | null••••••••

Show child attributes

Any of

string

null

aws_secret_access_keystring | null••••••••

Show child attributes

Any of

string

null

aws_origination_numberstring | null

Show child attributes

Any of

string

null

twilioNotificationService_TwilioConfigResponse | null

Show child attributes

Any of

twilio_account_sidstring | null

Show child attributes

Any of

string

null

twilio_auth_tokenstring | null••••••••

Show child attributes

Any of

string

null

twilio_from_numberstring | null

Show child attributes

Any of

string

null

msg91NotificationService_MSG91ConfigResponse | null

Show child attributes

Any of

msg91_api_keystring | null••••••••

Show child attributes

Any of

string

null

msg91_sender_idstring | null

Show child attributes

Any of

string

null

msg91_flow_idstring | null

Show child attributes

Any of

string

null

msg91_routestring | null

Show child attributes

Any of

string

null

kaleyraNotificationService_KaleyraConfigResponse | null

Show child attributes

Any of

kaleyra_api_keystring | null••••••••

Show child attributes

Any of

string

null

kaleyra_account_sidstring | null

Show child attributes

Any of

string

null

kaleyra_sender_idstring | null

Show child attributes

Any of

string

null

africas_talkingNotificationService_AfricasTalkingConfigResponse | null

Show child attributes

Any of

africas_talking_usernamestring | null

Show child attributes

Any of

string

null

africas_talking_api_keystring | null••••••••

Show child attributes

Any of

string

null

africas_talking_shortcodestring | null

Show child attributes

Any of

string

null

generic_httpNotificationService_GenericHttpConfigResponse | null

Show child attributes

Any of

generic_sms_endpointstring | null

Show child attributes

Any of

string

null

generic_sms_methodstring | null

Show child attributes

Any of

string

null

generic_sms_auth_header_namestring | null

Show child attributes

Any of

string

null

generic_sms_auth_header_valuestring | null••••••••

Show child attributes

Any of

string

null

generic_sms_body_templatestring | null

Show child attributes

Any of

string

null

slackNotificationService_SlackConfigResponse | null

Show child attributes

Any of

slack_webhook_urlstring | null••••••••

Show child attributes

Any of

string

null

is_activebooleanrequired

created_atstringrequired

updated_atstringrequired

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Send Test Notification

POST

http://localhost:8012/api/v1/notification/test

Send Test Notification

curl -X POST 'http://localhost:8012/api/v1/notification/test' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "channel": "email",
  "recipient": "string",
  "subject": "Test Notification",
  "body": "This is a test notification from MQUAD Notification Service."
}'

const body = `{
  "channel": "email",
  "recipient": "string",
  "subject": "Test Notification",
  "body": "This is a test notification from MQUAD Notification Service."
}`;

const response = await fetch('http://localhost:8012/api/v1/notification/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "channel": "email",
  "recipient": "string",
  "subject": "Test Notification",
  "body": "This is a test notification from MQUAD Notification Service."
}'''

response = requests.post(
    'http://localhost:8012/api/v1/notification/test',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "channel": "email",
  "recipient": "string",
  "subject": "Test Notification",
  "body": "This is a test notification from MQUAD Notification Service."
}

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

channelstringemailsmsslackrequired

recipientstringrequired

subjectstring | nullTest Notification

Show child attributes

Any of

string

null

bodystringThis is a test notification from MQUAD Notification Service.

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Notification Service / History

History — Notification Service

List Notifications

GET

http://localhost:8012/api/v1/notification/history

List Notifications

curl -X GET 'http://localhost:8012/api/v1/notification/history?page=1&page_size=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8012/api/v1/notification/history?page=1&page_size=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8012/api/v1/notification/history?page=1&page_size=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

user_idstring | nullquery

notification_statusstring | nullquery

channelstring | nullquery

pageinteger1query

page_sizeinteger20query

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Cancel Notifications

POST

http://localhost:8012/api/v1/notification/cancel

Cancel Notifications

curl -X POST 'http://localhost:8012/api/v1/notification/cancel' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "recipient": "user@example.com"
}'

const body = `{
  "recipient": "user@example.com"
}`;

const response = await fetch('http://localhost:8012/api/v1/notification/cancel', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "recipient": "user@example.com"
}'''

response = requests.post(
    'http://localhost:8012/api/v1/notification/cancel',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "recipient": "user@example.com"
}

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

recipientstring<email>required

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get Notification

GET

http://localhost:8012/api/v1/notification/{notification_id}

Get Notification

curl -X GET 'http://localhost:8012/api/v1/notification/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8012/api/v1/notification/550e8400-e29b-41d4-a716-446655440000', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8012/api/v1/notification/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

notification_idstring<uuid>requiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityNotificationService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Audit Service

Audit logs, compliance queries, export

Audit Service / Health

Health — Audit Service

Audit Service / Audit Logs

Audit Logs — Audit Service

Ingest Audit Log

POST

http://localhost:8013/api/v1/audit/logs

Ingest a new audit log entry.

Ingest Audit Log

curl -X POST 'http://localhost:8013/api/v1/audit/logs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "action": "create",
  "actor_email": "admin@acme.org",
  "actor_id": "550e8400-e29b-41d4-a716-446655440001",
  "actor_type": "admin",
  "data_classification": "internal",
  "duration_ms": 45,
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "user.created",
  "http_method": "POST",
  "http_path": "/api/v1/users",
  "http_status": 201,
  "ip_address": "192.168.1.1",
  "log_schema_version": "1.0",
  "metadata": {
    "role": "viewer"
  },
  "request_id": "req-12345678",
  "resource_id": "550e8400-e29b-41d4-a716-446655440003",
  "resource_type": "User",
  "service_name": "backend",
  "status": "success",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440002",
  "trace_id": "trace-12345678"
}'

const body = `{
  "action": "create",
  "actor_email": "admin@acme.org",
  "actor_id": "550e8400-e29b-41d4-a716-446655440001",
  "actor_type": "admin",
  "data_classification": "internal",
  "duration_ms": 45,
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "user.created",
  "http_method": "POST",
  "http_path": "/api/v1/users",
  "http_status": 201,
  "ip_address": "192.168.1.1",
  "log_schema_version": "1.0",
  "metadata": {
    "role": "viewer"
  },
  "request_id": "req-12345678",
  "resource_id": "550e8400-e29b-41d4-a716-446655440003",
  "resource_type": "User",
  "service_name": "backend",
  "status": "success",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440002",
  "trace_id": "trace-12345678"
}`;

const response = await fetch('http://localhost:8013/api/v1/audit/logs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "action": "create",
  "actor_email": "admin@acme.org",
  "actor_id": "550e8400-e29b-41d4-a716-446655440001",
  "actor_type": "admin",
  "data_classification": "internal",
  "duration_ms": 45,
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "user.created",
  "http_method": "POST",
  "http_path": "/api/v1/users",
  "http_status": 201,
  "ip_address": "192.168.1.1",
  "log_schema_version": "1.0",
  "metadata": {
    "role": "viewer"
  },
  "request_id": "req-12345678",
  "resource_id": "550e8400-e29b-41d4-a716-446655440003",
  "resource_type": "User",
  "service_name": "backend",
  "status": "success",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440002",
  "trace_id": "trace-12345678"
}'''

response = requests.post(
    'http://localhost:8013/api/v1/audit/logs',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "action": "create",
  "actor_email": "admin@acme.org",
  "actor_id": "550e8400-e29b-41d4-a716-446655440001",
  "actor_type": "admin",
  "data_classification": "internal",
  "duration_ms": 45,
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "user.created",
  "http_method": "POST",
  "http_path": "/api/v1/users",
  "http_status": 201,
  "ip_address": "192.168.1.1",
  "log_schema_version": "1.0",
  "metadata": {
    "role": "viewer"
  },
  "request_id": "req-12345678",
  "resource_id": "550e8400-e29b-41d4-a716-446655440003",
  "resource_type": "User",
  "service_name": "backend",
  "status": "success",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440002",
  "trace_id": "trace-12345678"
}

{
  "id": "string",
  "event_id": "string",
  "event_type": "string",
  "log_schema_version": "string",
  "service_name": "string",
  "action": "string",
  "actor_type": "string",
  "actor_id": "string",
  "actor_email": "string",
  "actor_name": "string",
  "tenant_id": "string",
  "tenant_name": "string",
  "resource_type": "string",
  "resource_id": "string",
  "resource_name": "string",
  "status": "string",
  "category": "string",
  "severity": "string",
  "description": "string",
  "failure_reason": "string",
  "correlation_id": "string",
  "ip_address": "string",
  "user_agent": "string",
  "request_id": "string",
  "trace_id": "string",
  "parent_trace_id": "string",
  "http_method": "string",
  "http_path": "string",
  "http_status": 0,
  "duration_ms": 0,
  "metadata": {},
  "data_classification": "string",
  "checksum": "string",
  "created_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

event_idstring | null

Unique event ID for idempotency

Show child attributes

Any of

string

null

event_typestring | null

Type of event (e.g., user.created)

Show child attributes

Any of

string

null

log_schema_versionstring | null1.0

Schema version

Show child attributes

Any of

string

null

service_namestringrequired

Name of the service producing the event

actionstringrequired

Action performed (create, update, delete, read, login, etc.)

actor_typestring | null

Type of actor

Show child attributes

Any of

stringuseradminsysteminterviewersupervisor

null

actor_idstring | null

ID of the actor

Show child attributes

Any of

string

null

actor_emailstring | null

Email of the actor

Show child attributes

Any of

string

null

actor_namestring | null

Display name of the actor

Show child attributes

Any of

string

null

tenant_idstring | null

Tenant ID

Show child attributes

Any of

string

null

tenant_namestring | null

Display name of the tenant

Show child attributes

Any of

string

null

resource_typestring | null

Type of resource

Show child attributes

Any of

string

null

resource_idstring | null

ID of the resource

Show child attributes

Any of

string

null

resource_namestring | null

Display name of the resource

Show child attributes

Any of

string

null

statusstring | nullsuccess

Event status

Show child attributes

Any of

stringsuccessfailureerror

null

categorystring | null

Event category for filtering

Show child attributes

Any of

stringAUTHENTICATIONUSER_MANAGEMENTROLE_ACCESSSURVEY_LIFECYCLERESPONSE_DATAINTERVIEWCONSENTEXPORTINTEGRATIONSYNCMEDIACONFIGURATIONSECURITYSYSTEMREVIEWNOTIFICATIONCOMPLIANCE

null

severitystring | nullINFO

Event severity level

Show child attributes

Any of

stringINFOWARNINGCRITICAL

null

descriptionstring | null

Human-readable event description

Show child attributes

Any of

string

null

failure_reasonstring | null

Reason for failure if status is failure/error

Show child attributes

Any of

string

null

correlation_idstring | null

Cross-service correlation ID

Show child attributes

Any of

string

null

ip_addressstring | null

Client IP address

Show child attributes

Any of

string

null

user_agentstring | null

Client user agent

Show child attributes

Any of

string

null

request_idstring | null

Request ID for correlation

Show child attributes

Any of

string

null

trace_idstring | null

Trace ID for cross-service correlation

Show child attributes

Any of

string

null

parent_trace_idstring | null

Parent trace ID

Show child attributes

Any of

string

null

http_methodstring | null

HTTP method

Show child attributes

Any of

string

null

http_pathstring | null

HTTP path

Show child attributes

Any of

string

null

http_statusinteger | null

HTTP status code

Show child attributes

Any of

integer

null

duration_msinteger | null

Request duration in milliseconds

Show child attributes

Any of

integer

null

metadataobject | null

Additional event metadata

Show child attributes

Any of

object

null

event_idempotency_keystring | null

Key for deduplication

Show child attributes

Any of

string

null

data_classificationstring | nullinternal

Data classification level

Show child attributes

Any of

stringpublicinternalsensitiverestricted

null

Example

{
  "action": "create",
  "actor_email": "admin@acme.org",
  "actor_id": "550e8400-e29b-41d4-a716-446655440001",
  "actor_type": "admin",
  "data_classification": "internal",
  "duration_ms": 45,
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "user.created",
  "http_method": "POST",
  "http_path": "/api/v1/users",
  "http_status": 201,
  "ip_address": "192.168.1.1",
  "log_schema_version": "1.0",
  "metadata": {
    "role": "viewer"
  },
  "request_id": "req-12345678",
  "resource_id": "550e8400-e29b-41d4-a716-446655440003",
  "resource_type": "User",
  "service_name": "backend",
  "status": "success",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440002",
  "trace_id": "trace-12345678"
}

Response

201CreatedAuditService_AuditLogResponse

Successful Response

Response fields application/json

idstringrequired

event_idstring | null

Show child attributes

Any of

string

null

event_typestring | null

Show child attributes

Any of

string

null

log_schema_versionstring | null

Show child attributes

Any of

string

null

service_namestringrequired

actionstringrequired

actor_typestring | null

Show child attributes

Any of

string

null

actor_idstring | null

Show child attributes

Any of

string

null

actor_emailstring | null

Show child attributes

Any of

string

null

actor_namestring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

tenant_namestring | null

Show child attributes

Any of

string

null

resource_typestring | null

Show child attributes

Any of

string

null

resource_idstring | null

Show child attributes

Any of

string

null

resource_namestring | null

Show child attributes

Any of

string

null

statusstring | null

Show child attributes

Any of

string

null

categorystring | null

Show child attributes

Any of

string

null

severitystring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

failure_reasonstring | null

Show child attributes

Any of

string

null

correlation_idstring | null

Show child attributes

Any of

string

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

request_idstring | null

Show child attributes

Any of

string

null

trace_idstring | null

Show child attributes

Any of

string

null

parent_trace_idstring | null

Show child attributes

Any of

string

null

http_methodstring | null

Show child attributes

Any of

string

null

http_pathstring | null

Show child attributes

Any of

string

null

http_statusinteger | null

Show child attributes

Any of

integer

null

duration_msinteger | null

Show child attributes

Any of

integer

null

metadataobject | null

Show child attributes

Any of

object

null

data_classificationstring | null

Show child attributes

Any of

string

null

checksumstringrequired

created_atstringrequired

422Unprocessable EntityAuditService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AuditService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

List System Audit Logs

GET

http://localhost:8013/api/v1/audit/logs/system

System-wide audit logs - for super:admin and host admin only.

SECURITY: full:access (tenant admin) is explicitly excluded. Tenant admins must not access other tenants' audit logs. Only super:admin and host:manage_tenants are permitted. See common/rbac_helpers.py L44.

This endpoint bypasses tenant filtering and allows viewing logs across all tenants. Optional tenant_id_filter can be used to scope to a specific tenant.

List System Audit Logs

curl -X GET 'http://localhost:8013/api/v1/audit/logs/system?skip=0&limit=50' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8013/api/v1/audit/logs/system?skip=0&limit=50', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8013/api/v1/audit/logs/system?skip=0&limit=50',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "event_id": "string",
      "event_type": "string",
      "log_schema_version": "string",
      "service_name": "string",
      "action": "string",
      "actor_type": "string",
      "actor_id": "string",
      "actor_email": "string",
      "actor_name": "string",
      "tenant_id": "string",
      "tenant_name": "string",
      "resource_type": "string",
      "resource_id": "string",
      "resource_name": "string",
      "status": "string",
      "category": "string",
      "severity": "string",
      "description": "string",
      "failure_reason": "string",
      "correlation_id": "string",
      "ip_address": "string",
      "user_agent": "string",
      "request_id": "string",
      "trace_id": "string",
      "parent_trace_id": "string",
      "http_method": "string",
      "http_path": "string",
      "http_status": 0,
      "duration_ms": 0,
      "metadata": {},
      "data_classification": "string",
      "checksum": "string",
      "created_at": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

service_namestring | nullquery

Filter by service name

actionstring | nullquery

Filter by action

user_idstring | nullquery

Filter by user ID

searchstring | nullquery

Search activity text

resource_typestring | nullquery

Filter by resource type

tenant_id_filterstring | nullquery

Filter by specific tenant ID

categorystring | nullquery

Filter by event category

date_fromstring | nullquery

Filter from date (ISO format)

date_tostring | nullquery

Filter to date (ISO format)

skipinteger>= 00query

Row offset

limitinteger[1, 500]50query

Page size

Response

200OKAuditService_AuditLogListResponse

Successful Response

Response fields application/json

itemsArray<AuditService_AuditLogResponse>required

Show child attributes

idstringrequired

event_idstring | null

Show child attributes

Any of

string

null

event_typestring | null

Show child attributes

Any of

string

null

log_schema_versionstring | null

Show child attributes

Any of

string

null

service_namestringrequired

actionstringrequired

actor_typestring | null

Show child attributes

Any of

string

null

actor_idstring | null

Show child attributes

Any of

string

null

actor_emailstring | null

Show child attributes

Any of

string

null

actor_namestring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

tenant_namestring | null

Show child attributes

Any of

string

null

resource_typestring | null

Show child attributes

Any of

string

null

resource_idstring | null

Show child attributes

Any of

string

null

resource_namestring | null

Show child attributes

Any of

string

null

statusstring | null

Show child attributes

Any of

string

null

categorystring | null

Show child attributes

Any of

string

null

severitystring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

failure_reasonstring | null

Show child attributes

Any of

string

null

correlation_idstring | null

Show child attributes

Any of

string

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

request_idstring | null

Show child attributes

Any of

string

null

trace_idstring | null

Show child attributes

Any of

string

null

parent_trace_idstring | null

Show child attributes

Any of

string

null

http_methodstring | null

Show child attributes

Any of

string

null

http_pathstring | null

Show child attributes

Any of

string

null

http_statusinteger | null

Show child attributes

Any of

integer

null

duration_msinteger | null

Show child attributes

Any of

integer

null

metadataobject | null

Show child attributes

Any of

object

null

data_classificationstring | null

Show child attributes

Any of

string

null

checksumstringrequired

created_atstringrequired

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityAuditService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AuditService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get Audit Log

GET

http://localhost:8013/api/v1/audit/logs/{log_id}

Get a specific audit log entry by ID.

Get Audit Log

curl -X GET 'http://localhost:8013/api/v1/audit/logs/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8013/api/v1/audit/logs/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8013/api/v1/audit/logs/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "event_id": "string",
  "event_type": "string",
  "log_schema_version": "string",
  "service_name": "string",
  "action": "string",
  "actor_type": "string",
  "actor_id": "string",
  "actor_email": "string",
  "actor_name": "string",
  "tenant_id": "string",
  "tenant_name": "string",
  "resource_type": "string",
  "resource_id": "string",
  "resource_name": "string",
  "status": "string",
  "category": "string",
  "severity": "string",
  "description": "string",
  "failure_reason": "string",
  "correlation_id": "string",
  "ip_address": "string",
  "user_agent": "string",
  "request_id": "string",
  "trace_id": "string",
  "parent_trace_id": "string",
  "http_method": "string",
  "http_path": "string",
  "http_status": 0,
  "duration_ms": 0,
  "metadata": {},
  "data_classification": "string",
  "checksum": "string",
  "created_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

log_idstringrequiredpath

Response

200OKAuditService_AuditLogResponse

Successful Response

Response fields application/json

idstringrequired

event_idstring | null

Show child attributes

Any of

string

null

event_typestring | null

Show child attributes

Any of

string

null

log_schema_versionstring | null

Show child attributes

Any of

string

null

service_namestringrequired

actionstringrequired

actor_typestring | null

Show child attributes

Any of

string

null

actor_idstring | null

Show child attributes

Any of

string

null

actor_emailstring | null

Show child attributes

Any of

string

null

actor_namestring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

tenant_namestring | null

Show child attributes

Any of

string

null

resource_typestring | null

Show child attributes

Any of

string

null

resource_idstring | null

Show child attributes

Any of

string

null

resource_namestring | null

Show child attributes

Any of

string

null

statusstring | null

Show child attributes

Any of

string

null

categorystring | null

Show child attributes

Any of

string

null

severitystring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

failure_reasonstring | null

Show child attributes

Any of

string

null

correlation_idstring | null

Show child attributes

Any of

string

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

request_idstring | null

Show child attributes

Any of

string

null

trace_idstring | null

Show child attributes

Any of

string

null

parent_trace_idstring | null

Show child attributes

Any of

string

null

http_methodstring | null

Show child attributes

Any of

string

null

http_pathstring | null

Show child attributes

Any of

string

null

http_statusinteger | null

Show child attributes

Any of

integer

null

duration_msinteger | null

Show child attributes

Any of

integer

null

metadataobject | null

Show child attributes

Any of

object

null

data_classificationstring | null

Show child attributes

Any of

string

null

checksumstringrequired

created_atstringrequired

422Unprocessable EntityAuditService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AuditService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Verify Chain Integrity

GET

http://localhost:8013/api/v1/audit/chain/verify

Verify the integrity of the audit log chain.

If resource_type and resource_id are provided, verify only events for that specific resource. Otherwise, verify the entire tenant's chain (existing behavior).

Verify Chain Integrity

curl -X GET 'http://localhost:8013/api/v1/audit/chain/verify?limit=1000' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8013/api/v1/audit/chain/verify?limit=1000', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8013/api/v1/audit/chain/verify?limit=1000',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

limitinteger[1, 10000]1000query

Number of logs to verify

resource_typestring | nullquery

Filter by resource type for targeted verification

resource_idstring | nullquery

Filter by resource ID for targeted verification

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityAuditService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AuditService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Audit Service / Compliance

Compliance — Audit Service

Get Data Access Report

GET

http://localhost:8013/api/v1/audit/compliance/gdpr/data-access/{user_id}

Get GDPR data access report for a specific user.

Get Data Access Report

curl -X GET 'http://localhost:8013/api/v1/audit/compliance/gdpr/data-access/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8013/api/v1/audit/compliance/gdpr/data-access/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8013/api/v1/audit/compliance/gdpr/data-access/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Record Consent

POST

http://localhost:8013/api/v1/audit/compliance/consent

Record or update a consent decision for a user.

Record Consent

curl -X POST 'http://localhost:8013/api/v1/audit/compliance/consent' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "user_id": "string",
  "consent_type": "string",
  "is_granted": true,
  "ip_address": "string",
  "metadata": {}
}'

const body = `{
  "user_id": "string",
  "consent_type": "string",
  "is_granted": true,
  "ip_address": "string",
  "metadata": {}
}`;

const response = await fetch('http://localhost:8013/api/v1/audit/compliance/consent', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "user_id": "string",
  "consent_type": "string",
  "is_granted": true,
  "ip_address": "string",
  "metadata": {}
}'''

response = requests.post(
    'http://localhost:8013/api/v1/audit/compliance/consent',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "user_id": "string",
  "consent_type": "string",
  "is_granted": true,
  "ip_address": "string",
  "metadata": {}
}

{
  "id": "string",
  "user_id": "string",
  "consent_type": "string",
  "is_granted": true,
  "granted_at": "string",
  "revoked_at": "string",
  "created_at": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Get User Consents

GET

http://localhost:8013/api/v1/audit/compliance/consent/{user_id}

Get all consent records for a specific user.

Get User Consents

curl -X GET 'http://localhost:8013/api/v1/audit/compliance/consent/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8013/api/v1/audit/compliance/consent/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8013/api/v1/audit/compliance/consent/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

[
  {
    "id": "string",
    "user_id": "string",
    "consent_type": "string",
    "is_granted": true,
    "granted_at": "string",
    "revoked_at": "string",
    "created_at": "string"
  }
]

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Audit Service / Export

Export — Audit Service

Export Audit Logs

POST

http://localhost:8013/api/v1/audit/export

Export audit logs in the specified format (json or csv).

Enforces a maximum of 50,000 records. Use date filtering to narrow the range when the export exceeds this limit.

Export Audit Logs

curl -X POST 'http://localhost:8013/api/v1/audit/export?format=json' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8013/api/v1/audit/export?format=json', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8013/api/v1/audit/export?format=json',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

formatstringjsonquery

Export format: json or csv

service_namestring | nullquery

Filter by service name

actionstring | nullquery

Filter by action

user_idstring | nullquery

Filter by user ID

resource_typestring | nullquery

Filter by resource type

date_fromstring | nullquery

Filter from date (ISO format)

date_tostring | nullquery

Filter to date (ISO format)

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityAuditService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<AuditService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Feature Flags Service

Feature flags, plans, flag evaluation

Feature Flags Service / Internal

Internal — Feature Flags Service

Invalidate Tenant Plan Context

POST

http://localhost:8014/internal/tenants/{tenant_id}/plan-context/invalidate

Internal endpoint: invalidate the cached plan context for a single tenant.

Used by backend service after Stripe webhook processing commits subscription state changes, ensuring entitlement propagation with minimal delay.

Authentication: X-Internal-Service header must equal "backend" and X-Service-Token must match the FEATURE_FLAGS_SERVICE_TOKEN.

Returns success even when no cache entry exists.

Invalidate Tenant Plan Context

curl -X POST 'http://localhost:8014/internal/tenants/string/plan-context/invalidate'

const response = await fetch('http://localhost:8014/internal/tenants/string/plan-context/invalidate', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8014/internal/tenants/string/plan-context/invalidate')
print(response.text)

{
  "tenant_id": "string",
  "invalidated": true,
  "message": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKFeatureFlagsService_InvalidateResponse

Successful Response

Response fields application/json

tenant_idstringrequired

invalidatedbooleanrequired

messagestringrequired

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Feature Flags Service / Feature Flags

Feature Flags — Feature Flags Service

List Flags

GET

http://localhost:8014/api/v1/flags

List all feature flags with pagination. Requires feature_flag:read.

List Flags

curl -X GET 'http://localhost:8014/api/v1/flags?skip=0&limit=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8014/api/v1/flags?skip=0&limit=20', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8014/api/v1/flags?skip=0&limit=20',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "items": [
    {
      "id": "string",
      "key": "string",
      "name": "string",
      "description": "string",
      "flag_type": "string",
      "is_enabled": true,
      "is_archived": true,
      "tags": [
        "string"
      ],
      "evaluation_count": 0,
      "last_evaluated_at": "string",
      "created_at": "string",
      "updated_at": "string",
      "plan_tier": "string",
      "feature_category": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

skipinteger>= 00query

limitinteger[1, 100]20query

Response

200OKFeatureFlagsService_FlagListResponse

Successful Response

Response fields application/json

itemsArray<FeatureFlagsService_FlagResponse>required

Show child attributes

idstringrequired

keystringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

flag_typestringrequired

default_valueanyrequired

is_enabledbooleanrequired

is_archivedbooleanrequired

tagsArray<string>required

evaluation_countintegerrequired

last_evaluated_atstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Create Flag

POST

http://localhost:8014/api/v1/flags

Create a new feature flag. Requires feature_flag:create.

Create Flag

curl -X POST 'http://localhost:8014/api/v1/flags' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "boolean",
  "default_value": false,
  "is_enabled": true,
  "tags": [
    "string"
  ],
  "environment": "string",
  "plan_tier": "string",
  "feature_category": "string"
}'

const body = `{
  "key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "boolean",
  "default_value": false,
  "is_enabled": true,
  "tags": [
    "string"
  ],
  "environment": "string",
  "plan_tier": "string",
  "feature_category": "string"
}`;

const response = await fetch('http://localhost:8014/api/v1/flags', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "boolean",
  "default_value": false,
  "is_enabled": true,
  "tags": [
    "string"
  ],
  "environment": "string",
  "plan_tier": "string",
  "feature_category": "string"
}'''

response = requests.post(
    'http://localhost:8014/api/v1/flags',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "boolean",
  "default_value": false,
  "is_enabled": true,
  "tags": [
    "string"
  ],
  "environment": "string",
  "plan_tier": "string",
  "feature_category": "string"
}

{
  "id": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "string",
  "is_enabled": true,
  "is_archived": true,
  "tags": [
    "string"
  ],
  "evaluation_count": 0,
  "last_evaluated_at": "string",
  "created_at": "string",
  "updated_at": "string",
  "plan_tier": "string",
  "feature_category": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

keystringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

flag_typestringboolean

default_valueanyfalse

is_enabledbooleantrue

tagsArray<string> | null

Show child attributes

Any of

Array<string>

null

environmentstring | null

Show child attributes

Any of

string

null

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

Response

201CreatedFeatureFlagsService_FlagResponse

Successful Response

Response fields application/json

idstringrequired

keystringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

flag_typestringrequired

default_valueanyrequired

is_enabledbooleanrequired

is_archivedbooleanrequired

tagsArray<string>required

evaluation_countintegerrequired

last_evaluated_atstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Get Flag

GET

http://localhost:8014/api/v1/flags/{flag_key}

Get a feature flag by key. Requires feature_flag:read.

Get Flag

curl -X GET 'http://localhost:8014/api/v1/flags/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8014/api/v1/flags/string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8014/api/v1/flags/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "string",
  "is_enabled": true,
  "is_archived": true,
  "tags": [
    "string"
  ],
  "evaluation_count": 0,
  "last_evaluated_at": "string",
  "created_at": "string",
  "updated_at": "string",
  "plan_tier": "string",
  "feature_category": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

flag_keystringrequiredpath

Response

200OKFeatureFlagsService_FlagResponse

Successful Response

Response fields application/json

idstringrequired

keystringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

flag_typestringrequired

default_valueanyrequired

is_enabledbooleanrequired

is_archivedbooleanrequired

tagsArray<string>required

evaluation_countintegerrequired

last_evaluated_atstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Update Flag

PUT

http://localhost:8014/api/v1/flags/{flag_key}

Update a feature flag. Requires feature_flag:update.

Update Flag

curl -X PUT 'http://localhost:8014/api/v1/flags/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "string",
  "description": "string",
  "is_enabled": true,
  "tags": [
    "string"
  ],
  "plan_tier": "string",
  "feature_category": "string"
}'

const body = `{
  "name": "string",
  "description": "string",
  "is_enabled": true,
  "tags": [
    "string"
  ],
  "plan_tier": "string",
  "feature_category": "string"
}`;

const response = await fetch('http://localhost:8014/api/v1/flags/string', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "name": "string",
  "description": "string",
  "is_enabled": true,
  "tags": [
    "string"
  ],
  "plan_tier": "string",
  "feature_category": "string"
}'''

response = requests.put(
    'http://localhost:8014/api/v1/flags/string',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "name": "string",
  "description": "string",
  "is_enabled": true,
  "tags": [
    "string"
  ],
  "plan_tier": "string",
  "feature_category": "string"
}

{
  "id": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "string",
  "is_enabled": true,
  "is_archived": true,
  "tags": [
    "string"
  ],
  "evaluation_count": 0,
  "last_evaluated_at": "string",
  "created_at": "string",
  "updated_at": "string",
  "plan_tier": "string",
  "feature_category": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

default_valueany | null

Show child attributes

Any of

any

null

is_enabledboolean | null

Show child attributes

Any of

boolean

null

tagsArray<string> | null

Show child attributes

Any of

Array<string>

null

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

Parameters

flag_keystringrequiredpath

Response

200OKFeatureFlagsService_FlagResponse

Successful Response

Response fields application/json

idstringrequired

keystringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

flag_typestringrequired

default_valueanyrequired

is_enabledbooleanrequired

is_archivedbooleanrequired

tagsArray<string>required

evaluation_countintegerrequired

last_evaluated_atstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Delete Flag

DELETE

http://localhost:8014/api/v1/flags/{flag_key}

Delete a feature flag and all associated rules/evaluations. Requires feature_flag:delete.

Delete Flag

curl -X DELETE 'http://localhost:8014/api/v1/flags/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8014/api/v1/flags/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'http://localhost:8014/api/v1/flags/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

422

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

flag_keystringrequiredpath

Response

200OKany

Successful Response

Response fields application/json

any

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Toggle Flag

POST

http://localhost:8014/api/v1/flags/{flag_key}/toggle

Toggle a feature flag's enabled state. Requires feature_flag:toggle.

Toggle Flag

curl -X POST 'http://localhost:8014/api/v1/flags/string/toggle' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8014/api/v1/flags/string/toggle', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8014/api/v1/flags/string/toggle',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "string",
  "is_enabled": true,
  "is_archived": true,
  "tags": [
    "string"
  ],
  "evaluation_count": 0,
  "last_evaluated_at": "string",
  "created_at": "string",
  "updated_at": "string",
  "plan_tier": "string",
  "feature_category": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

flag_keystringrequiredpath

Response

200OKFeatureFlagsService_FlagResponse

Successful Response

Response fields application/json

idstringrequired

keystringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

flag_typestringrequired

default_valueanyrequired

is_enabledbooleanrequired

is_archivedbooleanrequired

tagsArray<string>required

evaluation_countintegerrequired

last_evaluated_atstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Archive Flag

POST

http://localhost:8014/api/v1/flags/{flag_key}/archive

Archive a feature flag (disables and hides from list). Requires feature_flag:update.

Archive has no verb of its own in the catalog. It is mapped to update rather than delete because it is reversible -- the flag row and its rules survive, and only the archived state changes.

Archive Flag

curl -X POST 'http://localhost:8014/api/v1/flags/string/archive' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8014/api/v1/flags/string/archive', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'http://localhost:8014/api/v1/flags/string/archive',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "id": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "string",
  "is_enabled": true,
  "is_archived": true,
  "tags": [
    "string"
  ],
  "evaluation_count": 0,
  "last_evaluated_at": "string",
  "created_at": "string",
  "updated_at": "string",
  "plan_tier": "string",
  "feature_category": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

flag_keystringrequiredpath

Response

200OKFeatureFlagsService_FlagResponse

Successful Response

Response fields application/json

idstringrequired

keystringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

flag_typestringrequired

default_valueanyrequired

is_enabledbooleanrequired

is_archivedbooleanrequired

tagsArray<string>required

evaluation_countintegerrequired

last_evaluated_atstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Feature Flags Service / Flag Evaluation

Flag Evaluation — Feature Flags Service

Evaluate Flag

POST

http://localhost:8014/api/v1/evaluate

Evaluate a single feature flag against the provided context.

Evaluate Flag

curl -X POST 'http://localhost:8014/api/v1/evaluate' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "flag_key": "string",
  "context": {}
}'

const body = `{
  "flag_key": "string",
  "context": {}
}`;

const response = await fetch('http://localhost:8014/api/v1/evaluate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "flag_key": "string",
  "context": {}
}'''

response = requests.post(
    'http://localhost:8014/api/v1/evaluate',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "flag_key": "string",
  "context": {}
}

{
  "flag_key": "string",
  "is_enabled": true,
  "matched_rule": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

flag_keystringrequired

contextobject | null

Show child attributes

Any of

object

null

Response

200OKFeatureFlagsService_EvaluateResponse

Successful Response

Response fields application/json

flag_keystringrequired

valueanyrequired

is_enabledbooleanrequired

matched_rulestring | null

Show child attributes

Any of

string

null

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Evaluate Batch

POST

http://localhost:8014/api/v1/evaluate/batch

Evaluate multiple feature flags in a single request.

Evaluate Batch

curl -X POST 'http://localhost:8014/api/v1/evaluate/batch' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "flags": [
    {
      "flag_key": "string",
      "context": {}
    }
  ]
}'

const body = `{
  "flags": [
    {
      "flag_key": "string",
      "context": {}
    }
  ]
}`;

const response = await fetch('http://localhost:8014/api/v1/evaluate/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "flags": [
    {
      "flag_key": "string",
      "context": {}
    }
  ]
}'''

response = requests.post(
    'http://localhost:8014/api/v1/evaluate/batch',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "flags": [
    {
      "flag_key": "string",
      "context": {}
    }
  ]
}

{
  "results": [
    {
      "flag_key": "string",
      "is_enabled": true,
      "matched_rule": "string"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

flagsArray<FeatureFlagsService_EvaluateRequest>required

Show child attributes

flag_keystringrequired

contextobject | null

Show child attributes

Any of

object

null

Response

200OKFeatureFlagsService_BatchEvaluateResponse

Successful Response

Response fields application/json

resultsArray<FeatureFlagsService_EvaluateResponse>required

Show child attributes

flag_keystringrequired

valueanyrequired

is_enabledbooleanrequired

matched_rulestring | null

Show child attributes

Any of

string

null

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Authorization

HTTPBearerhttp (bearer)

Feature Flags Service / Health

Health — Feature Flags Service

Feature Flags Service / Plans

Plans — Feature Flags Service

List Plans

GET

http://localhost:8014/api/v1/plans

List all available subscription plans and their features.

List Plans

curl -X GET 'http://localhost:8014/api/v1/plans'

const response = await fetch('http://localhost:8014/api/v1/plans', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8014/api/v1/plans')
print(response.text)

200

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "price_id": "string",
      "amount": 0,
      "currency": "string",
      "interval": "string",
      "features": [
        {
          "key": "string",
          "canonical_key": "string",
          "name": "string",
          "description": "string",
          "flag_type": "string",
          "value": true,
          "category": "string",
          "unit": "string",
          "ui_label": "string",
          "upgrade_message": "string",
          "error_code": "string",
          "override_allowed": true
        }
      ],
      "limits": [
        {
          "key": "string",
          "canonical_key": "string",
          "name": "string",
          "value": 0,
          "category": "string",
          "scope": "string",
          "reset_period": "string",
          "unlimited": false,
          "custom_override": false,
          "unit": "string",
          "ui_label": "string",
          "counting_rule": "string",
          "upgrade_message": "string",
          "error_code": "string",
          "override_allowed": true
        }
      ]
    }
  ]
}

Response

200OKFeatureFlagsService_PlanListResponse

Successful Response

Response fields application/json

itemsArray<FeatureFlagsService_PlanDto>required

Show child attributes

idstringrequired

namestringrequired

descriptionstringrequired

price_idstringrequired

amountnumberrequired

currencystringrequired

intervalstringrequired

featuresArray<FeatureFlagsService_PlanFeatureDto>required

Show child attributes

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

descriptionstringrequired

flag_typestringrequired

valueboolean | integer | stringrequired

Show child attributes

Any of

boolean

integer

string

categorystringrequired

unitstring | null

Show child attributes

Any of

string

null

ui_labelstring | null

Show child attributes

Any of

string

null

upgrade_messagestring | null

Show child attributes

Any of

string

null

error_codestring | null

Show child attributes

Any of

string

null

override_allowedbooleantrue

limitsArray<FeatureFlagsService_PlanLimitDto>

Show child attributes

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

valueintegerrequired

categorystringrequired

scopestringrequired

reset_periodstring | null

Show child attributes

Any of

string

null

unlimitedbooleanfalse

custom_overridebooleanfalse

unitstring | null

Show child attributes

Any of

string

null

ui_labelstring | null

Show child attributes

Any of

string

null

counting_rulestring | null

Show child attributes

Any of

string

null

upgrade_messagestring | null

Show child attributes

Any of

string

null

error_codestring | null

Show child attributes

Any of

string

null

override_allowedbooleantrue

Get Entitlement Catalogue

GET

http://localhost:8014/api/v1/plans/catalogue

Return the canonical Phase 2 entitlement catalogue metadata.

Get Entitlement Catalogue

curl -X GET 'http://localhost:8014/api/v1/plans/catalogue'

const response = await fetch('http://localhost:8014/api/v1/plans/catalogue', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8014/api/v1/plans/catalogue')
print(response.text)

200

{
  "items": [
    {
      "key": "string",
      "source_key": "string",
      "name": "string",
      "type": "string",
      "unit": "string",
      "category": "string",
      "scope": "tenant",
      "reset_period": "string",
      "counting_rule": "string",
      "ui_label": "string",
      "upgrade_message": "string",
      "error_code": "string",
      "override_allowed": true,
      "stale_acceptable": false,
      "requires_role_permission": true,
      "downgrade_policy": "string",
      "applicable_services": [
        "string"
      ]
    }
  ]
}

Response

200OKFeatureFlagsService_EntitlementCatalogueResponse

Successful Response

Response fields application/json

itemsArray<FeatureFlagsService_EntitlementCatalogueItem>required

Show child attributes

keystringrequired

source_keystringrequired

namestringrequired

typestringrequired

unitstring | null

Show child attributes

Any of

string

null

categorystringrequired

scopestringtenant

reset_periodstring | null

Show child attributes

Any of

string

null

counting_rulestringrequired

ui_labelstringrequired

upgrade_messagestringrequired

error_codestringrequired

override_allowedbooleantrue

stale_acceptablebooleanfalse

requires_role_permissionbooleantrue

downgrade_policystringrequired

applicable_servicesArray<string>required

Get Plan

GET

http://localhost:8014/api/v1/plans/{tier}

Get details for a specific plan tier.

Get Plan

curl -X GET 'http://localhost:8014/api/v1/plans/string'

const response = await fetch('http://localhost:8014/api/v1/plans/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8014/api/v1/plans/string')
print(response.text)

{
  "id": "string",
  "name": "string",
  "description": "string",
  "price_id": "string",
  "amount": 0,
  "currency": "string",
  "interval": "string",
  "features": [
    {
      "key": "string",
      "canonical_key": "string",
      "name": "string",
      "description": "string",
      "flag_type": "string",
      "value": true,
      "category": "string",
      "unit": "string",
      "ui_label": "string",
      "upgrade_message": "string",
      "error_code": "string",
      "override_allowed": true
    }
  ],
  "limits": [
    {
      "key": "string",
      "canonical_key": "string",
      "name": "string",
      "value": 0,
      "category": "string",
      "scope": "string",
      "reset_period": "string",
      "unlimited": false,
      "custom_override": false,
      "unit": "string",
      "ui_label": "string",
      "counting_rule": "string",
      "upgrade_message": "string",
      "error_code": "string",
      "override_allowed": true
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

tierstringrequiredpath

Response

200OKFeatureFlagsService_PlanDto

Successful Response

Response fields application/json

idstringrequired

namestringrequired

descriptionstringrequired

price_idstringrequired

amountnumberrequired

currencystringrequired

intervalstringrequired

featuresArray<FeatureFlagsService_PlanFeatureDto>required

Show child attributes

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

descriptionstringrequired

flag_typestringrequired

valueboolean | integer | stringrequired

Show child attributes

Any of

boolean

integer

string

categorystringrequired

unitstring | null

Show child attributes

Any of

string

null

ui_labelstring | null

Show child attributes

Any of

string

null

upgrade_messagestring | null

Show child attributes

Any of

string

null

error_codestring | null

Show child attributes

Any of

string

null

override_allowedbooleantrue

limitsArray<FeatureFlagsService_PlanLimitDto>

Show child attributes

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

valueintegerrequired

categorystringrequired

scopestringrequired

reset_periodstring | null

Show child attributes

Any of

string

null

unlimitedbooleanfalse

custom_overridebooleanfalse

unitstring | null

Show child attributes

Any of

string

null

ui_labelstring | null

Show child attributes

Any of

string

null

counting_rulestring | null

Show child attributes

Any of

string

null

upgrade_messagestring | null

Show child attributes

Any of

string

null

error_codestring | null

Show child attributes

Any of

string

null

override_allowedbooleantrue

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Tenant Plan Tier

GET

http://localhost:8014/api/v1/plans/{tenant_id}/tier

Get plan tier for a tenant. Looks up from backend API.

Get Tenant Plan Tier

curl -X GET 'http://localhost:8014/api/v1/plans/string/tier'

const response = await fetch('http://localhost:8014/api/v1/plans/string/tier', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8014/api/v1/plans/string/tier')
print(response.text)

{}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKobject

Successful Response

Response fields application/json

object

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Tenant Limits

GET

http://localhost:8014/api/v1/plans/{tenant_id}/limits

Get limits for a tenant.

Returns limit values based on tenant's plan tier. Used by quota-service and plan-enforcement-sdk.

Get Tenant Limits

curl -X GET 'http://localhost:8014/api/v1/plans/string/limits'

const response = await fetch('http://localhost:8014/api/v1/plans/string/limits', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8014/api/v1/plans/string/limits')
print(response.text)

{
  "items": [
    {}
  ],
  "tier": "string",
  "tenant_id": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKFeatureFlagsService_TenantLimitsResponse

Successful Response

Response fields application/json

itemsArray<object>required

tierstringrequired

tenant_idstringrequired

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Tenant Features

GET

http://localhost:8014/api/v1/plans/{tenant_id}/features

Get feature flags for a tenant.

Returns boolean feature flags based on tenant's plan tier. Used by plan-enforcement-sdk for feature gate checks.

Get Tenant Features

curl -X GET 'http://localhost:8014/api/v1/plans/string/features'

const response = await fetch('http://localhost:8014/api/v1/plans/string/features', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8014/api/v1/plans/string/features')
print(response.text)

{
  "items": [
    {}
  ],
  "tier": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKFeatureFlagsService_TenantFeaturesResponse

Successful Response

Response fields application/json

itemsArray<object>required

tierstringrequired

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Tenant Entitlements

GET

http://localhost:8014/api/v1/plans/{tenant_id}/entitlements

Get normalized plan limits, feature entitlements, and subscription state.

Get Tenant Entitlements

curl -X GET 'http://localhost:8014/api/v1/plans/string/entitlements'

const response = await fetch('http://localhost:8014/api/v1/plans/string/entitlements', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8014/api/v1/plans/string/entitlements')
print(response.text)

{
  "tenant_id": "string",
  "tier": "string",
  "subscription_status": "string",
  "active": true,
  "trial": true,
  "trial_end_at": "string",
  "dormant": true,
  "limits": [
    {
      "key": "string",
      "canonical_key": "string",
      "name": "string",
      "value": 0,
      "category": "resource",
      "scope": "tenant",
      "reset_period": "string",
      "unlimited": false,
      "custom_override": false
    }
  ],
  "features": [
    {}
  ]
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

tenant_idstringrequiredpath

Response

200OKFeatureFlagsService_TenantEntitlementsResponse

Successful Response

Response fields application/json

tenant_idstringrequired

tierstringrequired

subscription_statusstringrequired

activebooleanrequired

trialbooleanrequired

trial_end_atstring | null

Show child attributes

Any of

string

null

dormantbooleanrequired

limitsArray<FeatureFlagsService_LimitItem>required

Show child attributes

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

valueintegerrequired

categorystringresource

scopestringtenant

reset_periodstring | null

Show child attributes

Any of

string

null

unlimitedbooleanfalse

custom_overridebooleanfalse

featuresArray<object>required

422Unprocessable EntityFeatureFlagsService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Quota Service

Real-time quota check/consume/rollback for plan enforcement

Readiness Check

GET

http://localhost:6380/ready

Readiness check endpoint.

Readiness Check

curl -X GET 'http://localhost:6380/ready'

const response = await fetch('http://localhost:6380/ready', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:6380/ready')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Quota Service / Quota

Quota — Quota Service

Check Limit

POST

http://localhost:6380/api/v1/quota/check

Check if quota is available.

For time-based limits (responses_per_month, exports_per_month, api_calls_per_minute): checks Redis counters with monthly window reset.

For absolute limits (surveys, storage_mb, etc.): returns limit from plan but does NOT check Redis — each consumer service self-enforces from its own DB.

Check Limit

curl -X POST 'http://localhost:6380/api/v1/quota/check' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "limit_type": "string",
  "amount": 1
}'

const body = `{
  "limit_type": "string",
  "amount": 1
}`;

const response = await fetch('http://localhost:6380/api/v1/quota/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "limit_type": "string",
  "amount": 1
}'''

response = requests.post(
    'http://localhost:6380/api/v1/quota/check',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "limit_type": "string",
  "amount": 1
}

{
  "success": true,
  "allowed": true,
  "current": 0,
  "limit": 0,
  "remaining": 0,
  "reset_at": "2024-01-15T09:30:00Z",
  "unlimited": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to check quota availability.

limit_typestringrequired

Type of limit (e.g., 'surveys')

amountinteger>= 11

Amount to check

Response

200OKQuotaService_QuotaResponse

Successful Response

Response fields application/json

Response from quota operations.

successbooleanrequired

allowedbooleanrequired

currentintegerrequired

limitintegerrequired

remainingintegerrequired

reset_atstring | null

Show child attributes

Any of

string<date-time>

null

unlimitedbooleanfalse

422Unprocessable EntityQuotaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<QuotaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Consume Quota

POST

http://localhost:6380/api/v1/quota/consume

Consume quota after successful operation.

For time-based limits: atomically increments the Redis counter. For absolute limits: no-op (services self-track from their own DB).

Consume Quota

curl -X POST 'http://localhost:6380/api/v1/quota/consume' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "limit_type": "string",
  "amount": 1,
  "idempotency_key": "string"
}'

const body = `{
  "limit_type": "string",
  "amount": 1,
  "idempotency_key": "string"
}`;

const response = await fetch('http://localhost:6380/api/v1/quota/consume', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "limit_type": "string",
  "amount": 1,
  "idempotency_key": "string"
}'''

response = requests.post(
    'http://localhost:6380/api/v1/quota/consume',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "limit_type": "string",
  "amount": 1,
  "idempotency_key": "string"
}

{
  "success": true,
  "allowed": true,
  "current": 0,
  "limit": 0,
  "remaining": 0,
  "reset_at": "2024-01-15T09:30:00Z",
  "unlimited": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to consume quota.

limit_typestringrequired

Type of limit

amountinteger>= 11

Amount to consume

idempotency_keystring | null

Tenant-scoped usage idempotency key

Show child attributes

Any of

string

null

Response

200OKQuotaService_QuotaResponse

Successful Response

Response fields application/json

Response from quota operations.

successbooleanrequired

allowedbooleanrequired

currentintegerrequired

limitintegerrequired

remainingintegerrequired

reset_atstring | null

Show child attributes

Any of

string<date-time>

null

unlimitedbooleanfalse

422Unprocessable EntityQuotaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<QuotaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Rollback Quota

POST

http://localhost:6380/api/v1/quota/rollback

Rollback quota consumption.

For time-based limits: atomically decrements the Redis counter. For absolute limits: no-op (services self-track from their own DB).

Rollback Quota

curl -X POST 'http://localhost:6380/api/v1/quota/rollback' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "limit_type": "string",
  "amount": 1
}'

const body = `{
  "limit_type": "string",
  "amount": 1
}`;

const response = await fetch('http://localhost:6380/api/v1/quota/rollback', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "limit_type": "string",
  "amount": 1
}'''

response = requests.post(
    'http://localhost:6380/api/v1/quota/rollback',
    data=body.encode('utf-8'),
    headers={
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "limit_type": "string",
  "amount": 1
}

{
  "success": true,
  "allowed": true,
  "current": 0,
  "limit": 0,
  "remaining": 0,
  "reset_at": "2024-01-15T09:30:00Z",
  "unlimited": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Body

application/json

Request to rollback quota.

limit_typestringrequired

Type of limit

amountinteger>= 11

Amount to rollback

Response

200OKQuotaService_QuotaResponse

Successful Response

Response fields application/json

Response from quota operations.

successbooleanrequired

allowedbooleanrequired

currentintegerrequired

limitintegerrequired

remainingintegerrequired

reset_atstring | null

Show child attributes

Any of

string<date-time>

null

unlimitedbooleanfalse

422Unprocessable EntityQuotaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<QuotaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get Usage

GET

http://localhost:6380/api/v1/quota/usage/{limit_type}

Get current usage for a limit type.

For time-based limits: returns actual Redis counter. For absolute limits: returns limit from plan, current=0 (service self-reports).

Get Usage

curl -X GET 'http://localhost:6380/api/v1/quota/usage/string'

const response = await fetch('http://localhost:6380/api/v1/quota/usage/string', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:6380/api/v1/quota/usage/string')
print(response.text)

{
  "success": true,
  "allowed": true,
  "current": 0,
  "limit": 0,
  "remaining": 0,
  "reset_at": "2024-01-15T09:30:00Z",
  "unlimited": false
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "ctx": {}
    }
  ]
}

Parameters

limit_typestringrequiredpath

Response

200OKQuotaService_QuotaResponse

Successful Response

Response fields application/json

Response from quota operations.

successbooleanrequired

allowedbooleanrequired

currentintegerrequired

limitintegerrequired

remainingintegerrequired

reset_atstring | null

Show child attributes

Any of

string<date-time>

null

unlimitedbooleanfalse

422Unprocessable EntityQuotaService_HTTPValidationError

Validation Error

Response fields application/json

detailArray<QuotaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Get All Usage

GET

http://localhost:6380/api/v1/quota/usage

Get all usage counters for tenant.

Get All Usage

curl -X GET 'http://localhost:6380/api/v1/quota/usage'

const response = await fetch('http://localhost:6380/api/v1/quota/usage', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:6380/api/v1/quota/usage')
print(response.text)

200

{}

Response

200OKobject

Successful Response

Response fields application/json

object

Reset Tenant

POST

http://localhost:6380/api/v1/quota/reset

Reset all counters for tenant (admin only).

Reset Tenant

curl -X POST 'http://localhost:6380/api/v1/quota/reset'

const response = await fetch('http://localhost:6380/api/v1/quota/reset', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:6380/api/v1/quota/reset')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Platform Utilities / Health

Shared endpoints served by multiple services

Health Check

GET

http://localhost:8000/api/v1/health

Also served by Survey Service at http://localhost:8001.

Also served by Data Service at http://localhost:8002.

Also served by Sync Service at http://localhost:8003.

Also served by Analytics Service at http://localhost:8004.

Also served by Workspace Service at http://localhost:8006.

Also served by Webhook Service at http://localhost:8007.

Also served by Form Service at http://localhost:8010.

Also served by Media Service at http://localhost:8011.

Also served by Notification Service at http://localhost:8012.

Also served by Audit Service at http://localhost:8013.

Also served by Feature Flags Service at http://localhost:8014.

Health Check

curl -X GET 'http://localhost:8000/api/v1/health'

const response = await fetch('http://localhost:8000/api/v1/health', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8000/api/v1/health')
print(response.text)

200

{
  "status": "Ok",
  "postgres_status": "Ok",
  "redis_status": "Ok"
}

Response

200OKBackend_HealthCheckResponseDto

Successful Response

Response fields application/json

statusstringrequired

Example

Ok

postgres_statusstring | null

Show child attributes

Any of

string

null

Example

Ok

redis_statusstring | null

Show child attributes

Any of

string

null

Example

Ok

Health Check

GET

http://localhost:8009/health

Health check endpoint.

Also served by Quota Service at http://localhost:6380.

Health Check

curl -X GET 'http://localhost:8009/health'

const response = await fetch('http://localhost:8009/health', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8009/health')
print(response.text)

200

{}

Response

200OKobject

Successful Response

Response fields application/json

object

Readiness Check

GET

http://localhost:8010/api/v1/health/ready

Readiness check for Kubernetes/container orchestration.

Returns 200 if the service is ready to accept traffic.

Also served by Media Service at http://localhost:8011.

Also served by Notification Service at http://localhost:8012.

Also served by Audit Service at http://localhost:8013.

Also served by Feature Flags Service at http://localhost:8014.

Readiness Check

curl -X GET 'http://localhost:8010/api/v1/health/ready'

const response = await fetch('http://localhost:8010/api/v1/health/ready', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8010/api/v1/health/ready')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Liveness Check

GET

http://localhost:8010/api/v1/health/live

Liveness check for Kubernetes/container orchestration.

Returns 200 if the service is alive.

Also served by Media Service at http://localhost:8011.

Also served by Notification Service at http://localhost:8012.

Also served by Audit Service at http://localhost:8013.

Also served by Feature Flags Service at http://localhost:8014.

Liveness Check

curl -X GET 'http://localhost:8010/api/v1/health/live'

const response = await fetch('http://localhost:8010/api/v1/health/live', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8010/api/v1/health/live')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Platform Utilities / Metrics

Shared endpoints served by multiple services

Metrics

GET

http://localhost:8001/api/v1/metrics

Prometheus metrics endpoint

Also served by Data Service at http://localhost:8002.

Also served by Sync Service at http://localhost:8003.

Also served by Workspace Service at http://localhost:8006.

Also served by Media Service at http://localhost:8011.

Also served by Notification Service at http://localhost:8012.

Also served by Audit Service at http://localhost:8013.

Also served by Feature Flags Service at http://localhost:8014.

Metrics

curl -X GET 'http://localhost:8001/api/v1/metrics'

const response = await fetch('http://localhost:8001/api/v1/metrics', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('http://localhost:8001/api/v1/metrics')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Platform Utilities / Migrations

Shared endpoints served by multiple services

Run Migrations

POST

http://localhost:8001/api/v1/migrations/run

Run database migrations for tenant

Also served by Data Service at http://localhost:8002.

Also served by Sync Service at http://localhost:8003.

Also served by Analytics Service at http://localhost:8004.

Also served by Workspace Service at http://localhost:8006.

Also served by Webhook Service at http://localhost:8007.

Also served by Form Service at http://localhost:8010.

Also served by Media Service at http://localhost:8011.

Also served by Notification Service at http://localhost:8012.

Also served by Audit Service at http://localhost:8013.

Also served by Feature Flags Service at http://localhost:8014.

Run Migrations

curl -X POST 'http://localhost:8001/api/v1/migrations/run'

const response = await fetch('http://localhost:8001/api/v1/migrations/run', {
  method: 'POST',
});

const data = await response.text();

import requests

response = requests.post('http://localhost:8001/api/v1/migrations/run')
print(response.text)

Response

200OKany

Successful Response

Response fields application/json

any

Platform Utilities / Audit Logs

Shared endpoints served by multiple services

List Audit Logs

GET

http://localhost:8000/api/v1/audit/logs

Also served by Audit Service at http://localhost:8013.

List Audit Logs

curl -X GET 'http://localhost:8000/api/v1/audit/logs?limit=10&skip=0' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('http://localhost:8000/api/v1/audit/logs?limit=10&skip=0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.get(
    'http://localhost:8000/api/v1/audit/logs?limit=10&skip=0',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

{
  "total": 0,
  "items": [
    {
      "id": "string",
      "entity": "string",
      "service_name": "string",
      "action": "create",
      "changes": {},
      "user_id": "string",
      "timestamp": "",
      "tenant_id": "string",
      "actor_name": "string",
      "actor_email": "string",
      "resource_id": "string",
      "resource_name": "string",
      "category": "string",
      "severity": "string",
      "description": "string",
      "failure_reason": "string",
      "correlation_id": "string",
      "status": "string",
      "ip_address": "string",
      "user_agent": "string",
      "event_type": "string"
    }
  ],
  "has_next": true,
  "has_previous": true,
  "limit": 0,
  "skip": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Parameters

limitinteger10query

skipinteger0query

actionstring | nullquery

searchstring | nullquery

user_idstring | nullquery

service_namestring | nullquery

Filter by service name

resource_typestring | nullquery

Filter by resource type

categorystring | nullquery

Filter by event category

date_fromstring | nullquery

Filter from date (ISO format)

date_tostring | nullquery

Filter to date (ISO format)

Response

200OKBackend_AuditLogListDto

Successful Response

Response fields application/json

totalintegerrequired

itemsArray<Backend_AuditLogDto>required

Show child attributes

idstring | null

Show child attributes

Any of

string

null

entitystringrequired

service_namestring | null

Show child attributes

Any of

string

null

actionstringcreateupdatedeletereadloginlogouterrordownloadrequired

changesobject

user_idstring | null

Show child attributes

Any of

string

null

timestampstring

tenant_idstring | null

Show child attributes

Any of

string

null

actor_namestring | null

Show child attributes

Any of

string

null

actor_emailstring | null

Show child attributes

Any of

string

null

resource_idstring | null

Show child attributes

Any of

string

null

resource_namestring | null

Show child attributes

Any of

string

null

categorystring | null

Show child attributes

Any of

string

null

severitystring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

failure_reasonstring | null

Show child attributes

Any of

string

null

correlation_idstring | null

Show child attributes

Any of

string

null

statusstring | null

Show child attributes

Any of

string

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

event_typestring | null

Show child attributes

Any of

string

null

has_nextbooleanrequired

has_previousbooleanrequired

limitintegerrequired

skipintegerrequired

422Unprocessable EntityBackend_HTTPValidationError

Validation Error

Response fields application/json

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Authorization

OAuth2PasswordBeareroauth2

Models

Backend_ActivateTrialDto

object

addressBackend_BillingAddressDtorequired

Show child attributes

individual_namestringrequired

business_namestring | null

Show child attributes

Any of

string

null

line1stringrequired

line2string | null

Show child attributes

Any of

string

null

citystringrequired

statestringrequired

postal_codestringrequired

countrystringrequired

tax_idstring | null

Show child attributes

Any of

string

null

Example

{
  "address": {
    "individual_name": "string",
    "business_name": "string",
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string"
  },
  "tax_id": "string"
}

Backend_AppConfigurationDto

object

is_multi_tenant_enabledbooleanrequired

multi_tenancy_strategystringrequired

host_main_domainstringrequired

is_user_logged_inboolean | nullfalse

Show child attributes

Any of

boolean

null

user_preferencesBackend_UserPreferenceDto | null

Show child attributes

Any of

user_idstringrequired

preferencesobjectrequired

null

current_tenantBackend_TenantDto | null

Show child attributes

Any of

idstring | nullrequired

Show child attributes

Any of

string

null

namestringrequired

subdomainstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

custom_domainstring | nullrequired

Show child attributes

Any of

string

null

custom_domain_statusstringactivefailedactivation-progressfailed

featuresArray<Backend_FeatureDto>

Show child attributes

nameBackend_Featurechatreportanalyticsorganizationteamsstriperequired

enabledbooleanrequired

subscription_idstring | nullrequired

Show child attributes

Any of

string

null

plan_tierstringfree

is_trialbooleanfalse

trial_end_atstring | null

Show child attributes

Any of

string

null

has_had_trialbooleanfalse

is_dormantbooleanfalse

billing_individual_namestring | null

Show child attributes

Any of

string

null

billing_business_namestring | null

Show child attributes

Any of

string

null

billing_address_line1string | null

Show child attributes

Any of

string

null

billing_address_line2string | null

Show child attributes

Any of

string

null

billing_address_citystring | null

Show child attributes

Any of

string

null

billing_address_statestring | null

Show child attributes

Any of

string

null

billing_address_postal_codestring | null

Show child attributes

Any of

string

null

billing_address_countrystring | null

Show child attributes

Any of

string

null

tax_idstring | null

Show child attributes

Any of

string

null

environmentstringrequired

runtime_security_configBackend_RuntimeSecurityConfigConfigDto | null

Show child attributes

Any of

screenshot_prevention_modestringdisabled

root_detection_modestringwarning

biometric_required_modestringdisabled

session_timeout_minutesinteger0

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

background_sync_enabledbooleantrue

crash_reporting_enabledbooleantrue

telemetry_enabledbooleantrue

global_modestringwarning

version_idstring | null

Show child attributes

Any of

string

null

tenant_data_governancesArray<Backend_TenantDataGovernanceConfigDto> | null

Show child attributes

Any of

Array<Backend_TenantDataGovernanceConfigDto>

Show child attributes

tenant_idstringrequired

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<string> | null

Show child attributes

Any of

Array<string>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

version_idstring | null

Show child attributes

Any of

string

null

mobile_security_policyBackend_DeprecatedMobileSecurityPolicyConfigDto | null

Show child attributes

Any of

DEPRECATED: For old mobile clients. Remove after migration window.

global_modestringwarning

screenshot_prevention_modestringdisabled

root_detection_modestringwarning

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

biometric_required_modestringdisabled

session_timeout_minutesinteger0

null

Example

{
  "is_multi_tenant_enabled": true,
  "multi_tenancy_strategy": "string",
  "host_main_domain": "string",
  "is_user_logged_in": false,
  "user_preferences": {
    "user_id": "string",
    "preferences": {}
  },
  "current_tenant": {
    "id": "string",
    "name": "string",
    "subdomain": "string",
    "is_active": true,
    "custom_domain": "string",
    "custom_domain_status": "failed",
    "features": [],
    "subscription_id": "string",
    "plan_tier": "free",
    "is_trial": false,
    "trial_end_at": "string",
    "has_had_trial": false,
    "is_dormant": false,
    "billing_individual_name": "string",
    "billing_business_name": "string",
    "billing_address_line1": "string",
    "billing_address_line2": "string",
    "billing_address_city": "string",
    "billing_address_state": "string",
    "billing_address_postal_code": "string",
    "billing_address_country": "string",
    "tax_id": "string"
  },
  "environment": "string",
  "runtime_security_config": {
    "screenshot_prevention_mode": "disabled",
    "root_detection_mode": "warning",
    "biometric_required_mode": "disabled",
    "session_timeout_minutes": 0,
    "wifi_only_sync": false,
    "battery_aware_sync": false,
    "battery_low_threshold_percent": 20,
    "block_sync_on_roaming": false,
    "background_sync_enabled": true,
    "crash_reporting_enabled": true,
    "telemetry_enabled": true,
    "global_mode": "warning",
    "version_id": "string"
  },
  "tenant_data_governances": [
    {
      "tenant_id": "string",
      "max_offline_duration_hours": 0,
      "force_revalidation_hours": 0,
      "media_upload_max_size_mb": 50,
      "media_upload_allowed_types": [
        "string"
      ],
      "local_retention_days": 0,
      "remote_wipe_enabled": false,
      "version_id": "string"
    }
  ],
  "mobile_security_policy": {
    "global_mode": "warning",
    "screenshot_prevention_mode": "disabled",
    "root_detection_mode": "warning",
    "max_offline_duration_hours": 0,
    "force_revalidation_hours": 0,
    "media_upload_max_size_mb": 50,
    "media_upload_allowed_types": [],
    "wifi_only_sync": false,
    "battery_aware_sync": false,
    "battery_low_threshold_percent": 20,
    "block_sync_on_roaming": false,
    "local_retention_days": 0,
    "remote_wipe_enabled": false,
    "biometric_required_mode": "disabled",
    "session_timeout_minutes": 0
  }
}

Backend_AppVersionCheckResponseDto

object

latest_versionstringrequired

Example

2.1.0

download_urlstring | null

Show child attributes

Any of

string

null

Example

https://releases.mquad.local/v2.1.0/mquad.apk

checksum_sha256string | null

Show child attributes

Any of

string

null

Example

a1b2c3d4e5f6...

min_versionstring | null

Show child attributes

Any of

string

null

Example

1.5.0

release_notesstring | null

Show child attributes

Any of

string

null

Example

Fixed sync conflicts, improved offline stability

Example

{
  "latest_version": "2.1.0",
  "download_url": "https://releases.mquad.local/v2.1.0/mquad.apk",
  "checksum_sha256": "a1b2c3d4e5f6...",
  "min_version": "1.5.0",
  "release_notes": "Fixed sync conflicts, improved offline stability"
}

Backend_AuditEventIngestRequest

object

Client-originated audit event relayed to the centralized audit-service.

event_idstring | null

Show child attributes

Any of

string

null

event_typestring | null

Show child attributes

Any of

string

null

log_schema_versionstring | null1.0

Show child attributes

Any of

string

null

service_namestringfrontend

actionstringrequired

actor_typestring | null

Show child attributes

Any of

string

null

actor_idstring | null

Show child attributes

Any of

string

null

actor_emailstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

resource_typestring | null

Show child attributes

Any of

string

null

resource_idstring | null

Show child attributes

Any of

string

null

statusstring | nullsuccess

Show child attributes

Any of

string

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

request_idstring | null

Show child attributes

Any of

string

null

trace_idstring | null

Show child attributes

Any of

string

null

parent_trace_idstring | null

Show child attributes

Any of

string

null

http_methodstring | null

Show child attributes

Any of

string

null

http_pathstring | null

Show child attributes

Any of

string

null

http_statusinteger | null

Show child attributes

Any of

integer

null

duration_msinteger | null

Show child attributes

Any of

integer

null

metadataobject | null

Show child attributes

Any of

object

null

event_idempotency_keystring | null

Show child attributes

Any of

string

null

data_classificationstring | null

Show child attributes

Any of

string

null

Example

{
  "event_id": "string",
  "event_type": "string",
  "log_schema_version": "1.0",
  "service_name": "frontend",
  "action": "string",
  "actor_type": "string",
  "actor_id": "string",
  "actor_email": "string",
  "tenant_id": "string",
  "resource_type": "string",
  "resource_id": "string",
  "status": "success",
  "ip_address": "string",
  "user_agent": "string",
  "request_id": "string",
  "trace_id": "string",
  "parent_trace_id": "string",
  "http_method": "string",
  "http_path": "string",
  "http_status": 0,
  "duration_ms": 0,
  "metadata": {},
  "event_idempotency_key": "string",
  "data_classification": "string"
}

Backend_AuditLogDto

object

idstring | null

Show child attributes

Any of

string

null

entitystringrequired

service_namestring | null

Show child attributes

Any of

string

null

actionstringcreateupdatedeletereadloginlogouterrordownloadrequired

changesobject

user_idstring | null

Show child attributes

Any of

string

null

timestampstring

tenant_idstring | null

Show child attributes

Any of

string

null

actor_namestring | null

Show child attributes

Any of

string

null

actor_emailstring | null

Show child attributes

Any of

string

null

resource_idstring | null

Show child attributes

Any of

string

null

resource_namestring | null

Show child attributes

Any of

string

null

categorystring | null

Show child attributes

Any of

string

null

severitystring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

failure_reasonstring | null

Show child attributes

Any of

string

null

correlation_idstring | null

Show child attributes

Any of

string

null

statusstring | null

Show child attributes

Any of

string

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

event_typestring | null

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "entity": "string",
  "service_name": "string",
  "action": "create",
  "changes": {},
  "user_id": "string",
  "timestamp": "",
  "tenant_id": "string",
  "actor_name": "string",
  "actor_email": "string",
  "resource_id": "string",
  "resource_name": "string",
  "category": "string",
  "severity": "string",
  "description": "string",
  "failure_reason": "string",
  "correlation_id": "string",
  "status": "string",
  "ip_address": "string",
  "user_agent": "string",
  "event_type": "string"
}

Backend_AuditLogListDto

object

totalintegerrequired

itemsArray<Backend_AuditLogDto>required

Show child attributes

idstring | null

Show child attributes

Any of

string

null

entitystringrequired

service_namestring | null

Show child attributes

Any of

string

null

actionstringcreateupdatedeletereadloginlogouterrordownloadrequired

changesobject

user_idstring | null

Show child attributes

Any of

string

null

timestampstring

tenant_idstring | null

Show child attributes

Any of

string

null

actor_namestring | null

Show child attributes

Any of

string

null

actor_emailstring | null

Show child attributes

Any of

string

null

resource_idstring | null

Show child attributes

Any of

string

null

resource_namestring | null

Show child attributes

Any of

string

null

categorystring | null

Show child attributes

Any of

string

null

severitystring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

failure_reasonstring | null

Show child attributes

Any of

string

null

correlation_idstring | null

Show child attributes

Any of

string

null

statusstring | null

Show child attributes

Any of

string

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

event_typestring | null

Show child attributes

Any of

string

null

has_nextbooleanrequired

has_previousbooleanrequired

limitintegerrequired

skipintegerrequired

Example

{
  "total": 0,
  "items": [
    {
      "id": "string",
      "entity": "string",
      "service_name": "string",
      "action": "create",
      "changes": {},
      "user_id": "string",
      "timestamp": "",
      "tenant_id": "string",
      "actor_name": "string",
      "actor_email": "string",
      "resource_id": "string",
      "resource_name": "string",
      "category": "string",
      "severity": "string",
      "description": "string",
      "failure_reason": "string",
      "correlation_id": "string",
      "status": "string",
      "ip_address": "string",
      "user_agent": "string",
      "event_type": "string"
    }
  ],
  "has_next": true,
  "has_previous": true,
  "limit": 0,
  "skip": 0
}

Backend_AuthenticatorTransport

string

How an authenticator communicates to the client/browser.

Members: USB: USB wired connection NFC: Near Field Communication BLE: Bluetooth Low Energy INTERNAL: Direct connection (read: a platform authenticator) CABLE: Cloud Assisted Bluetooth Low Energy HYBRID: A combination of (often separate) data-transport and proximity mechanisms

https://www.w3.org/TR/webauthn-2/#enum-transport

Backend_AuthenticatorTransportusbnfcblesmart-cardinternalcablehybrid

Backend_BillingAddressDto

object

individual_namestringrequired

business_namestring | null

Show child attributes

Any of

string

null

line1stringrequired

line2string | null

Show child attributes

Any of

string

null

citystringrequired

statestringrequired

postal_codestringrequired

countrystringrequired

Example

{
  "individual_name": "string",
  "business_name": "string",
  "line1": "string",
  "line2": "string",
  "city": "string",
  "state": "string",
  "postal_code": "string",
  "country": "string"
}

Backend_BillingConfigDto

object

publishable_keystringrequired

Backend_BillingRecordDto

object

idstringrequired

created_atstringrequired

scopestringhosttenantrequired

actorstringtenantend_userrequired

user_idstring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

user_emailstring | null

Show child attributes

Any of

string

null

payment_typestringrequired

currencystringrequired

amountinteger | null

Show child attributes

Any of

integer

null

amount_formattedstring | null

Show child attributes

Any of

string

null

stripe_customer_idstring | null

Show child attributes

Any of

string

null

stripe_subscription_idstring | null

Show child attributes

Any of

string

null

stripe_session_idstring | null

Show child attributes

Any of

string

null

stripe_invoice_idstring | null

Show child attributes

Any of

string

null

stripe_payment_intent_idstring | null

Show child attributes

Any of

string

null

product_idstring | null

Show child attributes

Any of

string

null

price_idstring | null

Show child attributes

Any of

string

null

statusstringpendingrequires_payment_methodrequires_actionactivesucceededpayment_failedcanceledincompleterequired

current_period_endstring | null

Show child attributes

Any of

string

null

canceled_atstring | null

Show child attributes

Any of

string

null

cancellation_reasonstring | null

Show child attributes

Any of

string

null

invoice_urlstring | null

Show child attributes

Any of

string

null

invoice_pdf_urlstring | null

Show child attributes

Any of

string

null

receipt_urlstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

Example

{
  "id": "string",
  "created_at": "string",
  "scope": "host",
  "actor": "tenant",
  "user_id": "string",
  "user_name": "string",
  "user_email": "string",
  "payment_type": "string",
  "currency": "string",
  "amount": 0,
  "amount_formatted": "string",
  "stripe_customer_id": "string",
  "stripe_subscription_id": "string",
  "stripe_session_id": "string",
  "stripe_invoice_id": "string",
  "stripe_payment_intent_id": "string",
  "product_id": "string",
  "price_id": "string",
  "status": "pending",
  "current_period_end": "string",
  "canceled_at": "string",
  "cancellation_reason": "string",
  "invoice_url": "string",
  "invoice_pdf_url": "string",
  "receipt_url": "string",
  "metadata": {}
}

Backend_BillingRecordListDto

object

itemsArray<Backend_BillingRecordDto>required

Show child attributes

idstringrequired

created_atstringrequired

scopestringhosttenantrequired

actorstringtenantend_userrequired

user_idstring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

user_emailstring | null

Show child attributes

Any of

string

null

payment_typestringrequired

currencystringrequired

amountinteger | null

Show child attributes

Any of

integer

null

amount_formattedstring | null

Show child attributes

Any of

string

null

stripe_customer_idstring | null

Show child attributes

Any of

string

null

stripe_subscription_idstring | null

Show child attributes

Any of

string

null

stripe_session_idstring | null

Show child attributes

Any of

string

null

stripe_invoice_idstring | null

Show child attributes

Any of

string

null

stripe_payment_intent_idstring | null

Show child attributes

Any of

string

null

product_idstring | null

Show child attributes

Any of

string

null

price_idstring | null

Show child attributes

Any of

string

null

statusstringpendingrequires_payment_methodrequires_actionactivesucceededpayment_failedcanceledincompleterequired

current_period_endstring | null

Show child attributes

Any of

string

null

canceled_atstring | null

Show child attributes

Any of

string

null

cancellation_reasonstring | null

Show child attributes

Any of

string

null

invoice_urlstring | null

Show child attributes

Any of

string

null

invoice_pdf_urlstring | null

Show child attributes

Any of

string

null

receipt_urlstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

skipintegerrequired

limitintegerrequired

totalintegerrequired

has_previousbooleanrequired

has_nextbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "created_at": "string",
      "scope": "host",
      "actor": "tenant",
      "user_id": "string",
      "user_name": "string",
      "user_email": "string",
      "payment_type": "string",
      "currency": "string",
      "amount": 0,
      "amount_formatted": "string",
      "stripe_customer_id": "string",
      "stripe_subscription_id": "string",
      "stripe_session_id": "string",
      "stripe_invoice_id": "string",
      "stripe_payment_intent_id": "string",
      "product_id": "string",
      "price_id": "string",
      "status": "pending",
      "current_period_end": "string",
      "canceled_at": "string",
      "cancellation_reason": "string",
      "invoice_url": "string",
      "invoice_pdf_url": "string",
      "receipt_url": "string",
      "metadata": {}
    }
  ],
  "skip": 0,
  "limit": 0,
  "total": 0,
  "has_previous": true,
  "has_next": true
}

Backend_Body_bulk_upload_users_api_v1_users_bulk_upload_post

object

tenant_idstringrequired

Tenant ID to add users to

default_role_idstring | null

Default role ID for new users

Show child attributes

Any of

string

null

default_role_namestring | null

Default role name for new users (e.g., 'Admin', 'User')

Show child attributes

Any of

string

null

send_invitationbooleantrue

Whether to send invitation emails

filestring<binary>required

CSV or Excel file with user data

Backend_Body_login_api_v1_account_login_post

object

grant_typestring | null

Show child attributes

Any of

string

null

usernamestringrequired

passwordstring<password>required

scopestring

client_idstring | null

Show child attributes

Any of

string

null

client_secretstring | null<password>

Show child attributes

Any of

string

null

Backend_Body_login_host_admin_api_v1_account_login_host_admin_post

object

grant_typestring | null

Show child attributes

Any of

string

null

usernamestringrequired

passwordstring<password>required

scopestring

client_idstring | null

Show child attributes

Any of

string

null

client_secretstring | null<password>

Show child attributes

Any of

string

null

Backend_Body_login_new_api_v1_account_login_new_post

object

grant_typestring | null

Show child attributes

Any of

string

null

usernamestringrequired

passwordstring<password>required

scopestring

client_idstring | null

Show child attributes

Any of

string

null

client_secretstring | null<password>

Show child attributes

Any of

string

null

Backend_Body_login_super_admin_api_v1_account_login_super_admin_post

object

grant_typestring | null

Show child attributes

Any of

string

null

usernamestringrequired

passwordstring<password>required

scopestring

client_idstring | null

Show child attributes

Any of

string

null

client_secretstring | null<password>

Show child attributes

Any of

string

null

Backend_Body_passkey_register_api_v1_account_passkey_register_post

object

emailstring<email>required

credentialobjectrequired

Backend_Body_update_profile_picture_api_v1_users__user_id__update_profile_picture_put

object

filestring<binary>required

Backend_BulkUserRequestDto

object

user_idsArray<string>required

Backend_BulkUserUploadResponseDto

object

DTO for bulk user upload response

totalintegerrequired

successintegerrequired

failedintegerrequired

resultsArray<Backend_BulkUserUploadResultDto>required

Show child attributes

DTO for individual user upload result

emailstringrequired

successbooleanrequired

user_idstring | null

Show child attributes

Any of

string

null

messagestringrequired

errorstring | null

Show child attributes

Any of

string

null

Example

{
  "total": 0,
  "success": 0,
  "failed": 0,
  "results": [
    {
      "email": "string",
      "success": true,
      "user_id": "string",
      "message": "string",
      "error": "string"
    }
  ]
}

Backend_BulkUserUploadResultDto

object

DTO for individual user upload result

emailstringrequired

successbooleanrequired

user_idstring | null

Show child attributes

Any of

string

null

messagestringrequired

errorstring | null

Show child attributes

Any of

string

null

Backend_CeleryMetricsDto

object

workers_onlineintegerrequired

active_tasksintegerrequired

scheduled_tasksintegerrequired

reserved_tasksintegerrequired

worker_detailsobjectrequired

Backend_ChangeEmailConfirmRequestDto

object

tokenstringrequired

Backend_ChangeEmailRequestDto

object

new_emailstring<email>required

Backend_ChangeEmailResponseDto

object

messagestringrequired

Backend_CheckoutRequestDto

object

price_idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

modestringpaymentsubscriptionsetupsubscription

emailstring<email>required

Backend_CheckoutResponseDto

object

checkout_urlstringrequired

Backend_CompleteIncompletePaymentRequestDto

object

subscription_idstringrequired

tenant_idstringrequired

Backend_ConfirmNativeSubscriptionRequestDto

object

billing_record_idstringrequired

Backend_CreateNativeSubscriptionRequestDto

object

price_idstringrequired

tenant_idstringrequired

modestringsubscriptionpaymentsubscription

emailstringrequired

Backend_CreateNotificationBannerSettingDto

object

is_enabledbooleanrequired

messagestring | null

Show child attributes

Any of

string

null

Backend_CreatePlanDto

object

currencystringusd

Must be a supported currency: https://docs.stripe.com/currencies

intervalstringmonthyearrequired

product_idstringrequired

The product whose pricing the created plan will represent. This must be the ID of an existing product.

amountintegerrequired

trial_period_daysinteger | null

Number of days for the trial period. Set > 0 to enable trials.

Show child attributes

Any of

integer

null

Backend_CreatePricingDto

object

currencystringusd

Currency code, e.g., 'usd'

unit_amountintegerrequired

A positive integer in cents (or 0 for a free price) representing how much to charge. One of unit_amount, unit_amount_decimal, or custom_unit_amount is required, unless billing_scheme=tiered.

productstringrequired

The ID of the product this price is associated with

activebooleantrue

Whether the price is active or not

recurringBackend_RecurringDtorequired

Show child attributes

intervalstringdayweekmonthyearmonth

Billing interval, e.g., 'month'

interval_countinteger1

Number of intervals between each billing cycle

usage_typestringlicensedmeteredlicensed

Example

{
  "currency": "usd",
  "unit_amount": 0,
  "product": "string",
  "active": true,
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "usage_type": "licensed"
  }
}

Backend_CreateProductDto

object

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

tax_codestring | null

Show child attributes

Any of

string

null

activebooleantrue

Backend_CreateRoleDto

object

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

is_immutablebooleanfalse

Backend_CreateRoleResponseDto

object

idstringrequired

Backend_CreateTenantDataGovernanceDto

object

tenant_idstringrequired

max_offline_duration_hoursinteger>= 00

force_revalidation_hoursinteger>= 00

media_upload_max_size_mbinteger[1, 500]50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger>= 00

remote_wipe_enabledbooleanfalse

Example

{
  "tenant_id": "string",
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false
}

Backend_CreateTenantDto

object

namestringrequired

subdomainstringrequired

admin_emailstring<email>required

admin_passwordstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

Example

{
  "name": "string",
  "subdomain": "string",
  "admin_email": "user@example.com",
  "admin_password": "string",
  "first_name": "string",
  "last_name": "string",
  "gender": "male"
}

Backend_CreateTenantResponseDto

object

idstringrequired

Backend_CreateUserDto

object

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gender | nullprefer_not_to_say

Show child attributes

Any of

Backend_Gendermalefemaleotherprefer_not_to_say

null

tenant_idstring | null

Show child attributes

Any of

string

null

role_idstring | null

Show child attributes

Any of

string

null

passwordstringrequired

sub_domainstring | null

Show child attributes

Any of

string

null

agreed_to_termsbooleantrue

Example

{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "prefer_not_to_say",
  "tenant_id": "string",
  "role_id": "string",
  "password": "string",
  "sub_domain": "string",
  "agreed_to_terms": true
}

Backend_CreateUserResponseDto

object

idstringrequired

Backend_DashboardMetricsDto

object

filterstringtodaythis_weeklast_3_monthsallrequired

joined_usersintegerrequired

total_usersintegerrequired

timeseriesArray<Backend_TimeSeriesDto>required

Show child attributes

time_or_datestringrequired

countintegerrequired

Backend_DeprecatedMobileSecurityPolicyConfigDto

object

DEPRECATED: For old mobile clients. Remove after migration window.

global_modestringwarning

screenshot_prevention_modestringdisabled

root_detection_modestringwarning

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

biometric_required_modestringdisabled

session_timeout_minutesinteger0

Example

{
  "global_mode": "warning",
  "screenshot_prevention_mode": "disabled",
  "root_detection_mode": "warning",
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "wifi_only_sync": false,
  "battery_aware_sync": false,
  "battery_low_threshold_percent": 20,
  "block_sync_on_roaming": false,
  "local_retention_days": 0,
  "remote_wipe_enabled": false,
  "biometric_required_mode": "disabled",
  "session_timeout_minutes": 0
}

Backend_DeprecatedMobileSecurityPolicyDto

object

Backward-compatible adapter for old mobile clients.

Maps from RuntimeSecurityConfig + TenantDataGovernance into the old monolithic MobileSecurityPolicyDto format. This is TEMPORARY — remove after migration window.

DEPRECATED: Use RuntimeSecurityConfigDto + TenantDataGovernanceDto instead.

idstring | null

Show child attributes

Any of

string

null

tenant_idstringrequired

global_modestringwarning

screenshot_prevention_modestringdisabled

root_detection_modestringwarning

biometric_required_modestringdisabled

session_timeout_minutesinteger0

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

Example

{
  "id": "string",
  "tenant_id": "string",
  "global_mode": "warning",
  "screenshot_prevention_mode": "disabled",
  "root_detection_mode": "warning",
  "biometric_required_mode": "disabled",
  "session_timeout_minutes": 0,
  "wifi_only_sync": false,
  "battery_aware_sync": false,
  "battery_low_threshold_percent": 20,
  "block_sync_on_roaming": false,
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false
}

Backend_DownloadAuditRequestDto

object

actionstring | null

Show child attributes

Any of

stringcreateupdatedeletereadloginlogouterrordownload

null

total_recordsintegerrequired

Backend_DownloadResponseDto

object

messagestringrequired

Backend_EnterpriseSignupDto

object

namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

companystring | null

Show child attributes

Any of

string

null

phonestring | null

Show child attributes

Any of

string

null

messagestring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

Backend_Feature

string

Backend_Featurechatreportanalyticsorganizationteamsstripe

Backend_FeatureDto

object

nameBackend_Featurechatreportanalyticsorganizationteamsstriperequired

enabledbooleanrequired

Backend_FrontendLogEntry

object

Frontend log entry model

timestampstringrequired

levelstringrequired

messagestringrequired

contextobject | null

Show child attributes

Any of

object

null

stackstring | null

Show child attributes

Any of

string

null

userAgentstring | null

Show child attributes

Any of

string

null

urlstring | null

Show child attributes

Any of

string

null

userIdstring | null

Show child attributes

Any of

string

null

tenantIdstring | null

Show child attributes

Any of

string

null

Example

{
  "timestamp": "string",
  "level": "string",
  "message": "string",
  "context": {},
  "stack": "string",
  "userAgent": "string",
  "url": "string",
  "userId": "string",
  "tenantId": "string"
}

Backend_Gender

string

Backend_Gendermalefemaleotherprefer_not_to_say

Backend_HTTPValidationError

object

detailArray<Backend_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

Backend_HasPasskeysDto

object

has_passkeysbooleanrequired

Backend_HealthCheckResponseDto

object

statusstringrequired

Example

Ok

postgres_statusstring | null

Show child attributes

Any of

string

null

Example

Ok

redis_statusstring | null

Show child attributes

Any of

string

null

Example

Ok

Backend_IncidentDto

object

idstringrequired

typestringrequired

severitystringcriticalwarninginforequired

messagestringrequired

tenant_idstring | nullrequired

Show child attributes

Any of

string

null

created_atstring<date-time>required

Backend_InfrastructureMetricsDto

object

celery_queue_sizeintegerrequired

redis_memory_mbnumberrequired

db_connectionsintegerrequired

storage_used_gbnumberrequired

webhook_failuresintegerrequired

Backend_InvoiceDto

object

idstringrequired

amount_dueinteger0

amount_paidinteger0

amount_remaininginteger0

amount_overpaidinteger0

attempt_countinteger0

attemptedbooleanfalse

auto_advancebooleanfalse

billing_reasonstring | null

Show child attributes

Any of

string

null

collection_methodstring | null

Show child attributes

Any of

string

null

createdintegerrequired

currencystringusd

customerstring | null

Show child attributes

Any of

string

null

customer_namestring | null

Show child attributes

Any of

string

null

statusstringopen

totalinteger0

receipt_numberstring | null

Show child attributes

Any of

string

null

amount_countrystring | null

Show child attributes

Any of

string

null

account_namestring | null

Show child attributes

Any of

string

null

invoice_pdfstring | null

Show child attributes

Any of

string

null

hosted_invoice_urlstring | null

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "amount_due": 0,
  "amount_paid": 0,
  "amount_remaining": 0,
  "amount_overpaid": 0,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "billing_reason": "string",
  "collection_method": "string",
  "created": 0,
  "currency": "usd",
  "customer": "string",
  "customer_name": "string",
  "status": "open",
  "total": 0,
  "receipt_number": "string",
  "amount_country": "string",
  "account_name": "string",
  "invoice_pdf": "string",
  "hosted_invoice_url": "string"
}

Backend_InvoiceListDto

object

itemsArray<Backend_InvoiceDto>required

Show child attributes

idstringrequired

amount_dueinteger0

amount_paidinteger0

amount_remaininginteger0

amount_overpaidinteger0

attempt_countinteger0

attemptedbooleanfalse

auto_advancebooleanfalse

billing_reasonstring | null

Show child attributes

Any of

string

null

collection_methodstring | null

Show child attributes

Any of

string

null

createdintegerrequired

currencystringusd

customerstring | null

Show child attributes

Any of

string

null

customer_namestring | null

Show child attributes

Any of

string

null

statusstringopen

totalinteger0

receipt_numberstring | null

Show child attributes

Any of

string

null

amount_countrystring | null

Show child attributes

Any of

string

null

account_namestring | null

Show child attributes

Any of

string

null

invoice_pdfstring | null

Show child attributes

Any of

string

null

hosted_invoice_urlstring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipinteger0

limitinteger10

has_nextbooleanfalse

has_previousbooleanfalse

Example

{
  "items": [
    {
      "id": "string",
      "amount_due": 0,
      "amount_paid": 0,
      "amount_remaining": 0,
      "amount_overpaid": 0,
      "attempt_count": 0,
      "attempted": false,
      "auto_advance": false,
      "billing_reason": "string",
      "collection_method": "string",
      "created": 0,
      "currency": "usd",
      "customer": "string",
      "customer_name": "string",
      "status": "open",
      "total": 0,
      "receipt_number": "string",
      "amount_country": "string",
      "account_name": "string",
      "invoice_pdf": "string",
      "hosted_invoice_url": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 10,
  "has_next": false,
  "has_previous": false
}

Backend_LoginResponseDto

object

Response after successful login with tenant selection info

userBackend_UserInfoDtorequired

User information returned after login

Show child attributes

idstringrequired

emailstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

user_codestring | null

Show child attributes

Any of

string

null

tenantsArray<Backend_TenantInfoDto>required

Show child attributes

Tenant information for selection

idstringrequired

namestringrequired

subdomainstring | null

Show child attributes

Any of

string

null

custom_domainstring | null

Show child attributes

Any of

string

null

logo_urlstring | null

Show child attributes

Any of

string

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

requires_tenant_selectionbooleanrequired

is_super_adminbooleanrequired

messagestringLogin successful

tokenstring | null

Show child attributes

Any of

string

null

refresh_tokenstring | null

Show child attributes

Any of

string

null

Example

{
  "user": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url": "string",
    "is_active": true,
    "activated_at": "2024-01-15T09:30:00Z",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    },
    "user_code": "string"
  },
  "tenants": [
    {
      "id": "string",
      "name": "string",
      "subdomain": "string",
      "custom_domain": "string",
      "logo_url": "string",
      "role": {
        "id": "string",
        "name": "string",
        "description": "string",
        "permissions": [],
        "is_immutable": false,
        "created_at": "string",
        "updated_at": "string",
        "tenant_id": "string",
        "scope": "tenant_custom",
        "users_count": 0
      }
    }
  ],
  "requires_tenant_selection": true,
  "is_super_admin": true,
  "message": "Login successful",
  "token": "string",
  "refresh_token": "string"
}

Backend_MagicLinkResponseDto

object

messagestringrequired

Backend_MeResponseDto

object

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

roleBackend_RoleDtorequired

Show child attributes

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

subscriptionBackend_SubscriptionPlanDto | nullrequired

Show child attributes

Any of

idstringrequired

plan_levelsobjectrequired

e.g., {'basic': 0, 'pro': 1, 'enterprise': 2}

Show child attributes

[key: string]integer

is_trialbooleanrequired

Indicates if the subscription is a trial

tenant_idstring | nullrequired

The tenant who owns the subscription

Show child attributes

Any of

string

null

actorstringrequired

who it is applied to, If end_user, then user_id must be set

user_idstring | nullrequired

The end user who has this subscription, if applicable

Show child attributes

Any of

string

null

plan_idstringrequired

Corresponding Stripe Price ID

plan_namestring | null

Plan name like Free, Starter, Pro, Enterprise

Show child attributes

Any of

string

null

stripe_subscription_statusstring | null

Stripe subscription status: active, trialing, incomplete, past_due, etc.

Show child attributes

Any of

string

null

trial_end_atstring | null

Trial end date if applicable

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "role_id": "string",
  "role_name": "string",
  "is_active": true,
  "member_active": true,
  "activated_at": "string",
  "image_url": "string",
  "user_code": "string",
  "created_at": "string",
  "updated_at": "string",
  "tenant_id": "string",
  "permissions": [
    "string"
  ],
  "agreed_to_terms": false,
  "role": {
    "id": "string",
    "name": "string",
    "description": "string",
    "permissions": [],
    "is_immutable": false,
    "created_at": "string",
    "updated_at": "string",
    "tenant_id": "string",
    "scope": "tenant_custom",
    "users_count": 0
  },
  "subscription": {
    "id": "string",
    "plan_levels": {},
    "is_trial": true,
    "tenant_id": "string",
    "actor": "string",
    "user_id": "string",
    "plan_id": "string",
    "plan_name": "string",
    "stripe_subscription_status": "string",
    "trial_end_at": "string"
  }
}

Backend_NativeSubscriptionResponseDto

object

client_secretstringrequired

subscription_idstringrequired

customer_idstringrequired

billing_record_idstringrequired

is_upgradebooleanfalse

requires_confirmationbooleantrue

Backend_NotificationBannerSettingDto

object

is_enabledbooleanrequired

messagestring | null

Show child attributes

Any of

string

null

idstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

Backend_OSMetricsDto

object

cpu_percentnumberrequired

memory_percentnumberrequired

memory_total_mbnumberrequired

memory_used_mbnumberrequired

Backend_PasswordResetConfirmRequestDto

object

new_passwordstringrequired

Backend_PasswordResetRequestDto

object

emailstring<email>required

Backend_PasswordResetResponseDto

object

messagestringrequired

Backend_PaymentMethodCardDto

object

brandstringrequired

last4stringrequired

exp_monthintegerrequired

exp_yearintegerrequired

countrystring | null

Show child attributes

Any of

string

null

Backend_PaymentMethodDto

object

idstringrequired

typestringrequired

cardBackend_PaymentMethodCardDto | null

Show child attributes

Any of

brandstringrequired

last4stringrequired

exp_monthintegerrequired

exp_yearintegerrequired

countrystring | null

Show child attributes

Any of

string

null

createdintegerrequired

is_defaultbooleanfalse

Example

{
  "id": "string",
  "type": "string",
  "card": {
    "brand": "string",
    "last4": "string",
    "exp_month": 0,
    "exp_year": 0,
    "country": "string"
  },
  "created": 0,
  "is_default": false
}

Backend_PaymentMethodListDto

object

itemsArray<Backend_PaymentMethodDto>required

Show child attributes

idstringrequired

typestringrequired

cardBackend_PaymentMethodCardDto | null

Show child attributes

Any of

brandstringrequired

last4stringrequired

exp_monthintegerrequired

exp_yearintegerrequired

countrystring | null

Show child attributes

Any of

string

null

createdintegerrequired

is_defaultbooleanfalse

customer_idstring | null

Show child attributes

Any of

string

null

Example

{
  "items": [
    {
      "id": "string",
      "type": "string",
      "card": {
        "brand": "string",
        "last4": "string",
        "exp_month": 0,
        "exp_year": 0,
        "country": "string"
      },
      "created": 0,
      "is_default": false
    }
  ],
  "customer_id": "string"
}

Backend_Permission

string

Backend_Permissionsuper:adminfull:accessuser:read_and_write_onlyuser:delete_onlyuser:self_read_and_write_onlyuser:role_assign_or_remove_onlyuser:view_onlyrole:view_onlyrole:read_and_write_onlyrole:delete_onlyrole:permission_read_and_write_onlyhost:manage_tenantsmanage:storage_settingsmanage:tenant_settingsmanage:billingmanage:payments_settingsmanage:products_and_pricingaudit_logs:view_onlyaudit_logs:downloadaudit_logs:writecompliance:manageforms:renderforms:previewforms:render_anonymousforms:submitforms:submit_anonymousforms:submit_offlineforms:draft_createforms:draft_readforms:draft_updateforms:draft_deleteforms:draft_read_allforms:session_createforms:session_readforms:session_deleteforms:session_read_allforms:config_readforms:config_writeforms:analytics_viewforms:analytics_exportforms:admindashboard:viewdashboard:readdashboard:createdashboard:updatedashboard:deletebilling:readconfig:readconfig:writesurvey:managesurvey:createsurvey:readsurvey:updatesurvey:deletesurvey:publishsurvey:unpublishsurvey:grant_accesssurvey:manage_accesssurvey:response_viewsurvey:response_downloadtemplate:readtemplate:createtemplate:updatetemplate:deletetemplate:managesubmission:createsubmission:readsubmission:updatesubmission:update_ownsubmission:deletesubmission:viewsubmission:exportsubmission:approvesubmission:assignworkspace:createworkspace:readworkspace:updateworkspace:deleteworkspace:manageworkspace:manage_membersproject:createproject:readproject:updateproject:deleteproject:manageanalytics:viewanalytics:exportanalytics:adminreport:viewreport:createexport:createexport:viewexport:downloadexport:cancelexport:template:createexport:template:viewwebhook:createwebhook:readwebhook:updatewebhook:deletewebhook:managesearch:executesearch:managenotification:sendnotification:viewnotification:read_allnotification:deletenotification:managenotification:template:viewnotification:template:createnotification:template:updatenotification:template:deletenotification:preferences:readnotification:preferences:writemedia:uploadmedia:readmedia:updatemedia:deletemedia:library_uploadmedia:library_readmedia:library_deletemedia:managefeature_flag:readfeature_flag:createfeature_flag:updatefeature_flag:deletefeature_flag:toggleresponse:createresponse:readresponse:updateresponse:deleteresponse:exportresponse:approveresponse:revise_ownattachment:createattachment:readattachment:deleteodk:viewodk:submitodk:manage

Backend_PermissionCategory

string

Logical grouping of permissions.

Backend_PermissionDangerLevel

string

Categorizes permissions by potential system impact.

stringlowmediumhighdangerous

Backend_PermissionDto

object

namestringrequired

display_namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

categoryBackend_PermissionCategory | null

Show child attributes

Any of

Logical grouping of permissions.

null

danger_levelBackend_PermissionDangerLevellowmediumhighdangerouslow

Categorizes permissions by potential system impact.

Backend_PermissionGroupedDto

object

Logical grouping of permissions.

permissionsArray<Backend_PermissionDto>required

Show child attributes

namestringrequired

display_namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

categoryBackend_PermissionCategory | null

Show child attributes

Any of

Logical grouping of permissions.

null

danger_levelBackend_PermissionDangerLevellowmediumhighdangerouslow

Categorizes permissions by potential system impact.

Example

{
  "category": "User Management",
  "permissions": [
    {
      "name": "string",
      "display_name": "string",
      "description": "string",
      "category": "User Management",
      "danger_level": "low"
    }
  ]
}

Backend_PlanDto

object

idstringrequired

activebooleanrequired

amountintegerrequired

amount_decimalstringrequired

billing_schemestringrequired

currencystringusd

intervalstringrequired

interval_countintegerrequired

productstringrequired

trial_period_daysinteger | null

Show child attributes

Any of

integer

null

usage_typestringrequired

Example

{
  "id": "string",
  "active": true,
  "amount": 0,
  "amount_decimal": "string",
  "billing_scheme": "string",
  "currency": "usd",
  "interval": "string",
  "interval_count": 0,
  "product": "string",
  "trial_period_days": 0,
  "usage_type": "string"
}

Backend_PlanListDto

object

itemsArray<Backend_PlanDto>required

Show child attributes

idstringrequired

activebooleanrequired

amountintegerrequired

amount_decimalstringrequired

billing_schemestringrequired

currencystringusd

intervalstringrequired

interval_countintegerrequired

productstringrequired

trial_period_daysinteger | null

Show child attributes

Any of

integer

null

usage_typestringrequired

totalintegerrequired

skipinteger0

limitinteger10

has_nextbooleanfalse

has_previousbooleanfalse

Example

{
  "items": [
    {
      "id": "string",
      "active": true,
      "amount": 0,
      "amount_decimal": "string",
      "billing_scheme": "string",
      "currency": "usd",
      "interval": "string",
      "interval_count": 0,
      "product": "string",
      "trial_period_days": 0,
      "usage_type": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 10,
  "has_next": false,
  "has_previous": false
}

Backend_PlanTierResponseDto

object

tierstringrequired

namestringrequired

Backend_PlatformHealthDto

object

statusstringhealthydegradeddownrequired

api_uptime_secondsnumberrequired

last_incident_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

active_incidentsintegerrequired

Backend_PricingDto

object

idstringrequired

currencystringrequired

unit_amountintegerrequired

productstringrequired

activebooleanrequired

recurringBackend_RecurringDtorequired

Show child attributes

intervalstringdayweekmonthyearmonth

Billing interval, e.g., 'month'

interval_countinteger1

Number of intervals between each billing cycle

usage_typestringlicensedmeteredlicensed

tax_behaviorstringrequired

typestringrequired

unit_amount_decimalstringrequired

Example

{
  "id": "string",
  "currency": "string",
  "unit_amount": 0,
  "product": "string",
  "active": true,
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "usage_type": "licensed"
  },
  "tax_behavior": "string",
  "type": "string",
  "unit_amount_decimal": "string"
}

Backend_PricingListDto

object

pricingsArray<Backend_PricingDto>required

Show child attributes

idstringrequired

currencystringrequired

unit_amountintegerrequired

productstringrequired

activebooleanrequired

recurringBackend_RecurringDtorequired

Show child attributes

intervalstringdayweekmonthyearmonth

Billing interval, e.g., 'month'

interval_countinteger1

Number of intervals between each billing cycle

usage_typestringlicensedmeteredlicensed

tax_behaviorstringrequired

typestringrequired

unit_amount_decimalstringrequired

has_morebooleanrequired

Example

{
  "pricings": [
    {
      "id": "string",
      "currency": "string",
      "unit_amount": 0,
      "product": "string",
      "active": true,
      "recurring": {
        "interval": "month",
        "interval_count": 1,
        "usage_type": "licensed"
      },
      "tax_behavior": "string",
      "type": "string",
      "unit_amount_decimal": "string"
    }
  ],
  "has_more": true
}

Backend_ProductDto

object

idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

tax_codestring | null

Show child attributes

Any of

string

null

activebooleanrequired

Backend_ProductListDto

object

productsArray<Backend_ProductDto>required

Show child attributes

idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

tax_codestring | null

Show child attributes

Any of

string

null

activebooleanrequired

has_morebooleanrequired

Backend_ProvisionUserDto

object

DTO for provisioning a user to a tenant (create or invite)

emailstring<email>required

role_idstringrequired

passwordstring | null

Show child attributes

Any of

string

null

first_namestring | null

Show child attributes

Any of

string

null

last_namestring | null

Show child attributes

Any of

string

null

genderBackend_Gender | null

Show child attributes

Any of

Backend_Gendermalefemaleotherprefer_not_to_say

null

Backend_ProvisionUserResponseDto

object

Response DTO for user provisioning

idstringrequired

statusstringrequired

messagestringrequired

Backend_RecurringDto

object

intervalstringdayweekmonthyearmonth

Billing interval, e.g., 'month'

interval_countinteger1

Number of intervals between each billing cycle

usage_typestringlicensedmeteredlicensed

Backend_RegisteredPasskeyCredentialsDto

object

credential_idstringrequired

public_keystringrequired

sigin_countintegerrequired

transportsArray<Backend_AuthenticatorTransport>usbnfcblesmart-cardinternalcablehybrid

created_atstring<date-time>required

last_used_atstring | null

Show child attributes

Any of

string<date-time>

null

Backend_RemoteWipeCommandDto

object

target_user_idstring | null

Show child attributes

Any of

string

null

reasonstring | null

Show child attributes

Any of

string

null

Backend_ReservedSubdomainsDto

object

subdomainsArray<string>required

Backend_RoleDto

object

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

Example

{
  "id": "string",
  "name": "string",
  "description": "string",
  "permissions": [],
  "is_immutable": false,
  "created_at": "string",
  "updated_at": "string",
  "tenant_id": "string",
  "scope": "tenant_custom",
  "users_count": 0
}

Backend_RoleListDto

object

itemsArray<Backend_RoleDto>required

Show child attributes

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

skipintegerrequired

limitintegerrequired

totalintegerrequired

has_previousbooleanrequired

has_nextbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    }
  ],
  "skip": 0,
  "limit": 0,
  "total": 0,
  "has_previous": true,
  "has_next": true
}

Backend_RoleScope

string

Defines where a role can be used.

stringplatformsystemtenant_custom

Backend_RuntimeSecurityConfigConfigDto

object

screenshot_prevention_modestringdisabled

root_detection_modestringwarning

biometric_required_modestringdisabled

session_timeout_minutesinteger0

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

background_sync_enabledbooleantrue

crash_reporting_enabledbooleantrue

telemetry_enabledbooleantrue

global_modestringwarning

version_idstring | null

Show child attributes

Any of

string

null

Example

{
  "screenshot_prevention_mode": "disabled",
  "root_detection_mode": "warning",
  "biometric_required_mode": "disabled",
  "session_timeout_minutes": 0,
  "wifi_only_sync": false,
  "battery_aware_sync": false,
  "battery_low_threshold_percent": 20,
  "block_sync_on_roaming": false,
  "background_sync_enabled": true,
  "crash_reporting_enabled": true,
  "telemetry_enabled": true,
  "global_mode": "warning",
  "version_id": "string"
}

Backend_RuntimeSecurityConfigDto

object

idstringsystem_default

screenshot_prevention_modestringstrictwarningdisableddisabled

root_detection_modestringstrictwarningdisabledwarning

biometric_required_modestringstrictwarningdisableddisabled

session_timeout_minutesinteger0

wifi_only_syncbooleanfalse

battery_aware_syncbooleanfalse

battery_low_threshold_percentinteger20

block_sync_on_roamingbooleanfalse

background_sync_enabledbooleantrue

crash_reporting_enabledbooleantrue

telemetry_enabledbooleantrue

global_modestringstrictwarningdisabledwarning

version_idstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

updated_bystring | null

Show child attributes

Any of

string

null

Example

{
  "id": "system_default",
  "screenshot_prevention_mode": "disabled",
  "root_detection_mode": "warning",
  "biometric_required_mode": "disabled",
  "session_timeout_minutes": 0,
  "wifi_only_sync": false,
  "battery_aware_sync": false,
  "battery_low_threshold_percent": 20,
  "block_sync_on_roaming": false,
  "background_sync_enabled": true,
  "crash_reporting_enabled": true,
  "telemetry_enabled": true,
  "global_mode": "warning",
  "version_id": "string",
  "updated_at": "string",
  "updated_by": "string"
}

Backend_SetPrimaryTenantDto

object

DTO for setting primary tenant

tenant_idstringrequired

Backend_SetupIntentDto

object

client_secretstringrequired

setup_intent_idstringrequired

Backend_SubdomainAvailabilityDto

object

is_availablebooleanrequired

reasonstring | null

Show child attributes

Any of

string

null

Backend_SubmissionMetricsDto

object

submissions_todayintegerrequired

submissions_this_weekintegerrequired

submissions_this_monthintegerrequired

submissions_trendArray<object>required

Show child attributes

[key: string]integer

Backend_SubscriptionMetricsDto

object

mrrnumberrequired

active_subscriptionsintegerrequired

trials_runningintegerrequired

cancelled_this_monthintegerrequired

plans_breakdownobjectrequired

Show child attributes

[key: string]integer

Backend_SubscriptionPlanDto

object

idstringrequired

plan_levelsobjectrequired

e.g., {'basic': 0, 'pro': 1, 'enterprise': 2}

Show child attributes

[key: string]integer

is_trialbooleanrequired

Indicates if the subscription is a trial

tenant_idstring | nullrequired

The tenant who owns the subscription

Show child attributes

Any of

string

null

actorstringrequired

who it is applied to, If end_user, then user_id must be set

user_idstring | nullrequired

The end user who has this subscription, if applicable

Show child attributes

Any of

string

null

plan_idstringrequired

Corresponding Stripe Price ID

plan_namestring | null

Plan name like Free, Starter, Pro, Enterprise

Show child attributes

Any of

string

null

stripe_subscription_statusstring | null

Stripe subscription status: active, trialing, incomplete, past_due, etc.

Show child attributes

Any of

string

null

trial_end_atstring | null

Trial end date if applicable

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "plan_levels": {},
  "is_trial": true,
  "tenant_id": "string",
  "actor": "string",
  "user_id": "string",
  "plan_id": "string",
  "plan_name": "string",
  "stripe_subscription_status": "string",
  "trial_end_at": "string"
}

Backend_SuperadminDashboardDto

object

tenantsBackend_TenantMetricsDtorequired

Show child attributes

total_tenantsintegerrequired

active_tenants_30dintegerrequired

new_tenants_this_monthintegerrequired

suspended_tenantsintegerrequired

submissionsBackend_SubmissionMetricsDtorequired

Show child attributes

submissions_todayintegerrequired

submissions_this_weekintegerrequired

submissions_this_monthintegerrequired

submissions_trendArray<object>required

Show child attributes

[key: string]integer

usersBackend_UserMetricsDtorequired

Show child attributes

total_usersintegerrequired

active_users_30dintegerrequired

new_users_this_monthintegerrequired

subscriptionsBackend_SubscriptionMetricsDtorequired

Show child attributes

mrrnumberrequired

active_subscriptionsintegerrequired

trials_runningintegerrequired

cancelled_this_monthintegerrequired

plans_breakdownobjectrequired

Show child attributes

[key: string]integer

infrastructureBackend_InfrastructureMetricsDtorequired

Show child attributes

celery_queue_sizeintegerrequired

redis_memory_mbnumberrequired

db_connectionsintegerrequired

storage_used_gbnumberrequired

webhook_failuresintegerrequired

incidentsArray<Backend_IncidentDto>required

Show child attributes

idstringrequired

typestringrequired

severitystringcriticalwarninginforequired

messagestringrequired

tenant_idstring | nullrequired

Show child attributes

Any of

string

null

created_atstring<date-time>required

platform_healthBackend_PlatformHealthDtorequired

Show child attributes

statusstringhealthydegradeddownrequired

api_uptime_secondsnumberrequired

last_incident_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

active_incidentsintegerrequired

submissions_trendArray<Backend_TimeSeriesPointDto>required

Show child attributes

datestringrequired

countintegerrequired

tenant_growth_trendArray<Backend_TimeSeriesPointDto>required

Show child attributes

datestringrequired

countintegerrequired

recent_tenant_activityArray<Backend_TenantActivityDto>required

Show child attributes

tenant_idstringrequired

tenant_namestringrequired

subdomainstringrequired

planstringrequired

users_countintegerrequired

surveys_countintegerrequired

submissions_countintegerrequired

last_activity_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

statusstringactiveidlesuspendedemptyrequired

Example

{
  "tenants": {
    "total_tenants": 0,
    "active_tenants_30d": 0,
    "new_tenants_this_month": 0,
    "suspended_tenants": 0
  },
  "submissions": {
    "submissions_today": 0,
    "submissions_this_week": 0,
    "submissions_this_month": 0,
    "submissions_trend": [
      {}
    ]
  },
  "users": {
    "total_users": 0,
    "active_users_30d": 0,
    "new_users_this_month": 0
  },
  "subscriptions": {
    "mrr": 0,
    "active_subscriptions": 0,
    "trials_running": 0,
    "cancelled_this_month": 0,
    "plans_breakdown": {}
  },
  "infrastructure": {
    "celery_queue_size": 0,
    "redis_memory_mb": 0,
    "db_connections": 0,
    "storage_used_gb": 0,
    "webhook_failures": 0
  },
  "incidents": [
    {
      "id": "string",
      "type": "string",
      "severity": "critical",
      "message": "string",
      "tenant_id": "string",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "platform_health": {
    "status": "healthy",
    "api_uptime_seconds": 0,
    "last_incident_at": "2024-01-15T09:30:00Z",
    "active_incidents": 0
  },
  "submissions_trend": [
    {
      "date": "string",
      "count": 0
    }
  ],
  "tenant_growth_trend": [
    {
      "date": "string",
      "count": 0
    }
  ],
  "recent_tenant_activity": [
    {
      "tenant_id": "string",
      "tenant_name": "string",
      "subdomain": "string",
      "plan": "string",
      "users_count": 0,
      "surveys_count": 0,
      "submissions_count": 0,
      "last_activity_at": "2024-01-15T09:30:00Z",
      "status": "active"
    }
  ]
}

Backend_SwitchTenantRequestDto

object

Request to switch active tenant

tenant_idstringrequired

Backend_SwitchTenantResponseDto

object

Response after switching tenant with new tokens and context

access_tokenstringrequired

token_typestringbearer

expires_inintegerrequired

refresh_tokenstringrequired

refresh_token_expires_inintegerrequired

userBackend_UserInfoDtorequired

User information returned after login

Show child attributes

idstringrequired

emailstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

user_codestring | null

Show child attributes

Any of

string

null

tenantBackend_TenantInfoDtorequired

Tenant information for selection

Show child attributes

idstringrequired

namestringrequired

subdomainstring | null

Show child attributes

Any of

string

null

custom_domainstring | null

Show child attributes

Any of

string

null

logo_urlstring | null

Show child attributes

Any of

string

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

previous_tenant_idstring | null

Show child attributes

Any of

string

null

messagestringTenant switched successfully

Example

{
  "access_token": "string",
  "token_type": "bearer",
  "expires_in": 0,
  "refresh_token": "string",
  "refresh_token_expires_in": 0,
  "user": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url": "string",
    "is_active": true,
    "activated_at": "2024-01-15T09:30:00Z",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    },
    "user_code": "string"
  },
  "tenant": {
    "id": "string",
    "name": "string",
    "subdomain": "string",
    "custom_domain": "string",
    "logo_url": "string",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    }
  },
  "previous_tenant_id": "string",
  "message": "Tenant switched successfully"
}

Backend_SystemMetricsResponseDto

object

os_metricsBackend_OSMetricsDtorequired

Show child attributes

cpu_percentnumberrequired

memory_percentnumberrequired

memory_total_mbnumberrequired

memory_used_mbnumberrequired

celery_metricsBackend_CeleryMetricsDto | null

Show child attributes

Any of

workers_onlineintegerrequired

active_tasksintegerrequired

scheduled_tasksintegerrequired

reserved_tasksintegerrequired

worker_detailsobjectrequired

null

Example

{
  "os_metrics": {
    "cpu_percent": 0,
    "memory_percent": 0,
    "memory_total_mb": 0,
    "memory_used_mb": 0
  },
  "celery_metrics": {
    "workers_online": 0,
    "active_tasks": 0,
    "scheduled_tasks": 0,
    "reserved_tasks": 0,
    "worker_details": {}
  }
}

Backend_TenantAccessUpdateDto

object

DTO for updating a user's per-tenant access (activate/deactivate in the active tenant)

is_activebooleanrequired

Backend_TenantActivityDto

object

tenant_idstringrequired

tenant_namestringrequired

subdomainstringrequired

planstringrequired

users_countintegerrequired

surveys_countintegerrequired

submissions_countintegerrequired

last_activity_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

statusstringactiveidlesuspendedemptyrequired

Example

{
  "tenant_id": "string",
  "tenant_name": "string",
  "subdomain": "string",
  "plan": "string",
  "users_count": 0,
  "surveys_count": 0,
  "submissions_count": 0,
  "last_activity_at": "2024-01-15T09:30:00Z",
  "status": "active"
}

Backend_TenantDataGovernanceConfigDto

object

tenant_idstringrequired

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<string> | null

Show child attributes

Any of

Array<string>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

version_idstring | null

Show child attributes

Any of

string

null

Example

{
  "tenant_id": "string",
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [
    "string"
  ],
  "local_retention_days": 0,
  "remote_wipe_enabled": false,
  "version_id": "string"
}

Backend_TenantDataGovernanceDto

object

idstring | null

Show child attributes

Any of

string

null

tenant_idstringrequired

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

version_idstring | null

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "tenant_id": "string",
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 50,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": false,
  "version_id": "string"
}

Backend_TenantDataGovernanceResponseDto

object

messagestringrequired

governanceBackend_TenantDataGovernanceDto | null

Show child attributes

Any of

idstring | null

Show child attributes

Any of

string

null

tenant_idstringrequired

max_offline_duration_hoursinteger0

force_revalidation_hoursinteger0

media_upload_max_size_mbinteger50

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger0

remote_wipe_enabledbooleanfalse

version_idstring | null

Show child attributes

Any of

string

null

Example

{
  "message": "string",
  "governance": {
    "id": "string",
    "tenant_id": "string",
    "max_offline_duration_hours": 0,
    "force_revalidation_hours": 0,
    "media_upload_max_size_mb": 50,
    "media_upload_allowed_types": [],
    "local_retention_days": 0,
    "remote_wipe_enabled": false,
    "version_id": "string"
  }
}

Backend_TenantDto

object

idstring | nullrequired

Show child attributes

Any of

string

null

namestringrequired

subdomainstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

custom_domainstring | nullrequired

Show child attributes

Any of

string

null

custom_domain_statusstringactivefailedactivation-progressfailed

featuresArray<Backend_FeatureDto>

Show child attributes

nameBackend_Featurechatreportanalyticsorganizationteamsstriperequired

enabledbooleanrequired

subscription_idstring | nullrequired

Show child attributes

Any of

string

null

plan_tierstringfree

is_trialbooleanfalse

trial_end_atstring | null

Show child attributes

Any of

string

null

has_had_trialbooleanfalse

is_dormantbooleanfalse

billing_individual_namestring | null

Show child attributes

Any of

string

null

billing_business_namestring | null

Show child attributes

Any of

string

null

billing_address_line1string | null

Show child attributes

Any of

string

null

billing_address_line2string | null

Show child attributes

Any of

string

null

billing_address_citystring | null

Show child attributes

Any of

string

null

billing_address_statestring | null

Show child attributes

Any of

string

null

billing_address_postal_codestring | null

Show child attributes

Any of

string

null

billing_address_countrystring | null

Show child attributes

Any of

string

null

tax_idstring | null

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "name": "string",
  "subdomain": "string",
  "is_active": true,
  "custom_domain": "string",
  "custom_domain_status": "failed",
  "features": [],
  "subscription_id": "string",
  "plan_tier": "free",
  "is_trial": false,
  "trial_end_at": "string",
  "has_had_trial": false,
  "is_dormant": false,
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}

Backend_TenantInfoDto

object

Tenant information for selection

idstringrequired

namestringrequired

subdomainstring | null

Show child attributes

Any of

string

null

custom_domainstring | null

Show child attributes

Any of

string

null

logo_urlstring | null

Show child attributes

Any of

string

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

Example

{
  "id": "string",
  "name": "string",
  "subdomain": "string",
  "custom_domain": "string",
  "logo_url": "string",
  "role": {
    "id": "string",
    "name": "string",
    "description": "string",
    "permissions": [],
    "is_immutable": false,
    "created_at": "string",
    "updated_at": "string",
    "tenant_id": "string",
    "scope": "tenant_custom",
    "users_count": 0
  }
}

Backend_TenantInvoiceExportDto

object

idstringrequired

invoice_numberstring | null

Show child attributes

Any of

string

null

createdintegerrequired

due_dateinteger | null

Show child attributes

Any of

integer

null

statusstringopen

currencystringusd

amount_dueinteger0

amount_paidinteger0

tax_amountinteger0

totalinteger0

billing_reasonstring | null

Show child attributes

Any of

string

null

customer_namestring | null

Show child attributes

Any of

string

null

tenant_namestring | null

Show child attributes

Any of

string

null

tenant_tax_idstring | null

Show child attributes

Any of

string

null

invoice_pdfstring | null

Show child attributes

Any of

string

null

hosted_invoice_urlstring | null

Show child attributes

Any of

string

null

line_itemsArray<Backend_TenantInvoiceLineItemDto>

Show child attributes

descriptionstring | null

Show child attributes

Any of

string

null

quantityinteger1

unit_amountinteger0

amountinteger0

currencystringusd

Example

{
  "id": "string",
  "invoice_number": "string",
  "created": 0,
  "due_date": 0,
  "status": "open",
  "currency": "usd",
  "amount_due": 0,
  "amount_paid": 0,
  "tax_amount": 0,
  "total": 0,
  "billing_reason": "string",
  "customer_name": "string",
  "tenant_name": "string",
  "tenant_tax_id": "string",
  "invoice_pdf": "string",
  "hosted_invoice_url": "string",
  "line_items": []
}

Backend_TenantInvoiceLineItemDto

object

descriptionstring | null

Show child attributes

Any of

string

null

quantityinteger1

unit_amountinteger0

amountinteger0

currencystringusd

Backend_TenantInvoiceListDto

object

itemsArray<Backend_TenantInvoiceExportDto>required

Show child attributes

idstringrequired

invoice_numberstring | null

Show child attributes

Any of

string

null

createdintegerrequired

due_dateinteger | null

Show child attributes

Any of

integer

null

statusstringopen

currencystringusd

amount_dueinteger0

amount_paidinteger0

tax_amountinteger0

totalinteger0

billing_reasonstring | null

Show child attributes

Any of

string

null

customer_namestring | null

Show child attributes

Any of

string

null

tenant_namestring | null

Show child attributes

Any of

string

null

tenant_tax_idstring | null

Show child attributes

Any of

string

null

invoice_pdfstring | null

Show child attributes

Any of

string

null

hosted_invoice_urlstring | null

Show child attributes

Any of

string

null

line_itemsArray<Backend_TenantInvoiceLineItemDto>

Show child attributes

descriptionstring | null

Show child attributes

Any of

string

null

quantityinteger1

unit_amountinteger0

amountinteger0

currencystringusd

totalintegerrequired

skipinteger0

limitinteger10

has_nextbooleanfalse

has_previousbooleanfalse

Example

{
  "items": [
    {
      "id": "string",
      "invoice_number": "string",
      "created": 0,
      "due_date": 0,
      "status": "open",
      "currency": "usd",
      "amount_due": 0,
      "amount_paid": 0,
      "tax_amount": 0,
      "total": 0,
      "billing_reason": "string",
      "customer_name": "string",
      "tenant_name": "string",
      "tenant_tax_id": "string",
      "invoice_pdf": "string",
      "hosted_invoice_url": "string",
      "line_items": []
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 10,
  "has_next": false,
  "has_previous": false
}

Backend_TenantListDto

object

itemsArray<Backend_TenantDto>required

Show child attributes

idstring | nullrequired

Show child attributes

Any of

string

null

namestringrequired

subdomainstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

custom_domainstring | nullrequired

Show child attributes

Any of

string

null

custom_domain_statusstringactivefailedactivation-progressfailed

featuresArray<Backend_FeatureDto>

Show child attributes

nameBackend_Featurechatreportanalyticsorganizationteamsstriperequired

enabledbooleanrequired

subscription_idstring | nullrequired

Show child attributes

Any of

string

null

plan_tierstringfree

is_trialbooleanfalse

trial_end_atstring | null

Show child attributes

Any of

string

null

has_had_trialbooleanfalse

is_dormantbooleanfalse

billing_individual_namestring | null

Show child attributes

Any of

string

null

billing_business_namestring | null

Show child attributes

Any of

string

null

billing_address_line1string | null

Show child attributes

Any of

string

null

billing_address_line2string | null

Show child attributes

Any of

string

null

billing_address_citystring | null

Show child attributes

Any of

string

null

billing_address_statestring | null

Show child attributes

Any of

string

null

billing_address_postal_codestring | null

Show child attributes

Any of

string

null

billing_address_countrystring | null

Show child attributes

Any of

string

null

tax_idstring | null

Show child attributes

Any of

string

null

skipintegerrequired

limitintegerrequired

totalintegerrequired

has_previousbooleanrequired

has_nextbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "subdomain": "string",
      "is_active": true,
      "custom_domain": "string",
      "custom_domain_status": "failed",
      "features": [],
      "subscription_id": "string",
      "plan_tier": "free",
      "is_trial": false,
      "trial_end_at": "string",
      "has_had_trial": false,
      "is_dormant": false,
      "billing_individual_name": "string",
      "billing_business_name": "string",
      "billing_address_line1": "string",
      "billing_address_line2": "string",
      "billing_address_city": "string",
      "billing_address_state": "string",
      "billing_address_postal_code": "string",
      "billing_address_country": "string",
      "tax_id": "string"
    }
  ],
  "skip": 0,
  "limit": 0,
  "total": 0,
  "has_previous": true,
  "has_next": true
}

Backend_TenantMetricsDto

object

total_tenantsintegerrequired

active_tenants_30dintegerrequired

new_tenants_this_monthintegerrequired

suspended_tenantsintegerrequired

Backend_TenantPlanContextResponseDto

object

tenant_idstringrequired

tierstringrequired

namestringrequired

subscription_statusstringinactive

is_activebooleanfalse

is_trialbooleanfalse

trial_end_atstring | null

Show child attributes

Any of

string

null

is_dormantbooleanfalse

featuresArray<object>

Example

{
  "tenant_id": "string",
  "tier": "string",
  "name": "string",
  "subscription_status": "inactive",
  "is_active": false,
  "is_trial": false,
  "trial_end_at": "string",
  "is_dormant": false,
  "features": [
    {}
  ]
}

Backend_TenantSelectionRequestDto

object

Request to select a tenant and get tokens

tenant_idstringrequired

Backend_TenantSelectionResponseDto

object

Response after tenant selection with tokens

access_tokenstringrequired

token_typestringbearer

expires_inintegerrequired

refresh_tokenstringrequired

refresh_token_expires_inintegerrequired

userBackend_UserInfoDtorequired

User information returned after login

Show child attributes

idstringrequired

emailstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

user_codestring | null

Show child attributes

Any of

string

null

tenantBackend_TenantInfoDto | null

Show child attributes

Any of

Tenant information for selection

idstringrequired

namestringrequired

subdomainstring | null

Show child attributes

Any of

string

null

custom_domainstring | null

Show child attributes

Any of

string

null

logo_urlstring | null

Show child attributes

Any of

string

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

Example

{
  "access_token": "string",
  "token_type": "bearer",
  "expires_in": 0,
  "refresh_token": "string",
  "refresh_token_expires_in": 0,
  "user": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url": "string",
    "is_active": true,
    "activated_at": "2024-01-15T09:30:00Z",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    },
    "user_code": "string"
  },
  "tenant": {
    "id": "string",
    "name": "string",
    "subdomain": "string",
    "custom_domain": "string",
    "logo_url": "string",
    "role": {
      "id": "string",
      "name": "string",
      "description": "string",
      "permissions": [],
      "is_immutable": false,
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "scope": "tenant_custom",
      "users_count": 0
    }
  }
}

Backend_TimeSeriesDto

object

time_or_datestringrequired

countintegerrequired

Backend_TimeSeriesPointDto

object

datestringrequired

countintegerrequired

Backend_TokenSetDto

object

refresh_tokenstringrequired

refresh_token_expires_inintegerrequired

access_tokenstringrequired

token_typestringrequired

expires_inintegerrequired

Backend_UpdateBillingAddressDto

object

addressBackend_BillingAddressDtorequired

Show child attributes

individual_namestringrequired

business_namestring | null

Show child attributes

Any of

string

null

line1stringrequired

line2string | null

Show child attributes

Any of

string

null

citystringrequired

statestringrequired

postal_codestringrequired

countrystringrequired

tax_idstring | null

Show child attributes

Any of

string

null

Example

{
  "address": {
    "individual_name": "string",
    "business_name": "string",
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string"
  },
  "tax_id": "string"
}

Backend_UpdatePlanDto

object

trial_period_daysintegerrequired

activebooleantrue

metadataobject | null

Show child attributes

Any of

object

null

Backend_UpdatePricingDto

object

activebooleanrequired

metadataobject | null

Show child attributes

Any of

object

null

tax_behaviorstring | null

Show child attributes

Any of

stringexclusiveinclusiveunspecified

null

Backend_UpdateRoleDto

object

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

is_immutablebooleanfalse

Backend_UpdateRolePermissionsDto

object

Backend_UpdateRuntimeSecurityConfigDto

object

screenshot_prevention_modestring | null

Show child attributes

Any of

stringstrictwarningdisabled

null

root_detection_modestring | null

Show child attributes

Any of

stringstrictwarningdisabled

null

biometric_required_modestring | null

Show child attributes

Any of

stringstrictwarningdisabled

null

session_timeout_minutesinteger | null

Show child attributes

Any of

integer[0, 1440]

null

wifi_only_syncboolean | null

Show child attributes

Any of

boolean

null

battery_aware_syncboolean | null

Show child attributes

Any of

boolean

null

battery_low_threshold_percentinteger | null

Show child attributes

Any of

integer[1, 100]

null

block_sync_on_roamingboolean | null

Show child attributes

Any of

boolean

null

background_sync_enabledboolean | null

Show child attributes

Any of

boolean

null

crash_reporting_enabledboolean | null

Show child attributes

Any of

boolean

null

telemetry_enabledboolean | null

Show child attributes

Any of

boolean

null

global_modestring | null

Show child attributes

Any of

stringstrictwarningdisabled

null

Example

{
  "screenshot_prevention_mode": "strict",
  "root_detection_mode": "strict",
  "biometric_required_mode": "strict",
  "session_timeout_minutes": 0,
  "wifi_only_sync": true,
  "battery_aware_sync": true,
  "battery_low_threshold_percent": 1,
  "block_sync_on_roaming": true,
  "background_sync_enabled": true,
  "crash_reporting_enabled": true,
  "telemetry_enabled": true,
  "global_mode": "strict"
}

Backend_UpdateTenantDataGovernanceDto

object

max_offline_duration_hoursinteger | null

Show child attributes

Any of

integer>= 0

null

force_revalidation_hoursinteger | null

Show child attributes

Any of

integer>= 0

null

media_upload_max_size_mbinteger | null

Show child attributes

Any of

integer[1, 500]

null

media_upload_allowed_typesArray<any> | null

Show child attributes

Any of

Array<any>

null

local_retention_daysinteger | null

Show child attributes

Any of

integer>= 0

null

remote_wipe_enabledboolean | null

Show child attributes

Any of

boolean

null

Example

{
  "max_offline_duration_hours": 0,
  "force_revalidation_hours": 0,
  "media_upload_max_size_mb": 1,
  "media_upload_allowed_types": [],
  "local_retention_days": 0,
  "remote_wipe_enabled": true
}

Backend_UpdateTenantDto

object

is_activeboolean | null

Show child attributes

Any of

boolean

null

is_dormantboolean | null

Show child attributes

Any of

boolean

null

custom_domainstring | null

Show child attributes

Any of

string

null

subscription_idstring | null

Show child attributes

Any of

string

null

plan_tierstring | null

Show child attributes

Any of

string

null

custom_domain_statusstring | null

Show child attributes

Any of

stringactivefailedactivation-progress

null

billing_individual_namestring | null

Show child attributes

Any of

string

null

billing_business_namestring | null

Show child attributes

Any of

string

null

billing_address_line1string | null

Show child attributes

Any of

string

null

billing_address_line2string | null

Show child attributes

Any of

string

null

billing_address_citystring | null

Show child attributes

Any of

string

null

billing_address_statestring | null

Show child attributes

Any of

string

null

billing_address_postal_codestring | null

Show child attributes

Any of

string

null

billing_address_countrystring | null

Show child attributes

Any of

string

null

tax_idstring | null

Show child attributes

Any of

string

null

Example

{
  "is_active": true,
  "is_dormant": true,
  "custom_domain": "string",
  "subscription_id": "string",
  "plan_tier": "string",
  "custom_domain_status": "active",
  "billing_individual_name": "string",
  "billing_business_name": "string",
  "billing_address_line1": "string",
  "billing_address_line2": "string",
  "billing_address_city": "string",
  "billing_address_state": "string",
  "billing_address_postal_code": "string",
  "billing_address_country": "string",
  "tax_id": "string"
}

Backend_UpdateTenantResponseDto

object

messagestringrequired

Backend_UpdateUserDto

object

first_namestring | null

Show child attributes

Any of

string

null

last_namestring | null

Show child attributes

Any of

string

null

emailstring | null

Show child attributes

Any of

string<email>

null

genderBackend_Gender | null

Show child attributes

Any of

Backend_Gendermalefemaleotherprefer_not_to_say

null

image_urlstring | null

Show child attributes

Any of

string

null

role_idstring | null

Show child attributes

Any of

string

null

is_activeboolean | null

Show child attributes

Any of

boolean

null

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

tenant_idstring | null

Show child attributes

Any of

string

null

passwordstring | null

Show child attributes

Any of

string

null

Example

{
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "image_url": "string",
  "role_id": "string",
  "is_active": true,
  "activated_at": "2024-01-15T09:30:00Z",
  "tenant_id": "string",
  "password": "string"
}

Backend_UserActivationRequestDto

object

tokenstringrequired

Backend_UserCountDto

object

totalintegerrequired

Backend_UserDto

object

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

Example

{
  "id": "string",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "gender": "male",
  "role_id": "string",
  "role_name": "string",
  "is_active": true,
  "member_active": true,
  "activated_at": "string",
  "image_url": "string",
  "user_code": "string",
  "created_at": "string",
  "updated_at": "string",
  "tenant_id": "string",
  "permissions": [
    "string"
  ],
  "agreed_to_terms": false
}

Backend_UserInfoDto

object

User information returned after login

idstringrequired

emailstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

activated_atstring | null

Show child attributes

Any of

string<date-time>

null

roleBackend_RoleDto | null

Show child attributes

Any of

idstringrequired

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_immutablebooleanfalse

created_atstring | null

Show child attributes

Any of

string

null

updated_atstring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

scopeBackend_RoleScopeplatformsystemtenant_customtenant_custom

Defines where a role can be used.

users_countinteger0

null

user_codestring | null

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "image_url": "string",
  "is_active": true,
  "activated_at": "2024-01-15T09:30:00Z",
  "role": {
    "id": "string",
    "name": "string",
    "description": "string",
    "permissions": [],
    "is_immutable": false,
    "created_at": "string",
    "updated_at": "string",
    "tenant_id": "string",
    "scope": "tenant_custom",
    "users_count": 0
  },
  "user_code": "string"
}

Backend_UserListDto

object

itemsArray<Backend_UserDto>required

Show child attributes

idstringrequired

first_namestringrequired

last_namestring | null

Show child attributes

Any of

string

null

emailstring<email>required

genderBackend_Gendermalefemaleotherprefer_not_to_sayrequired

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

is_activebooleanrequired

member_activebooleantrue

activated_atstring | null

Show child attributes

Any of

string

null

image_urlstring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

permissionsArray<string> | null

Show child attributes

Any of

Array<string>

null

agreed_to_termsbooleanfalse

skipintegerrequired

limitintegerrequired

totalintegerrequired

has_previousbooleanrequired

has_nextbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "first_name": "string",
      "last_name": "string",
      "email": "user@example.com",
      "gender": "male",
      "role_id": "string",
      "role_name": "string",
      "is_active": true,
      "member_active": true,
      "activated_at": "string",
      "image_url": "string",
      "user_code": "string",
      "created_at": "string",
      "updated_at": "string",
      "tenant_id": "string",
      "permissions": [
        "string"
      ],
      "agreed_to_terms": false
    }
  ],
  "skip": 0,
  "limit": 0,
  "total": 0,
  "has_previous": true,
  "has_next": true
}

Backend_UserMetricsDto

object

total_usersintegerrequired

active_users_30dintegerrequired

new_users_this_monthintegerrequired

Backend_UserPreferenceDto

object

user_idstringrequired

preferencesobjectrequired

Backend_UserProfileImageUpdateDto

object

image_urlstring | null

Show child attributes

Any of

string

null

Backend_UserResendActivationEmailRequestDto

object

emailstring<email>required

idstringrequired

first_namestringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

Backend_UserRoleUpdateRequestDto

object

role_idstringrequired

Backend_UserTenantCreateDto

object

DTO for creating user-tenant relationship

user_idstringrequired

tenant_idstringrequired

role_idstring | null

Show child attributes

Any of

string

null

is_primarybooleanfalse

is_activebooleantrue

Backend_UserTenantDto

object

DTO for user-tenant relationship

idstringrequired

user_idstringrequired

tenant_idstringrequired

tenant_namestring | null

Show child attributes

Any of

string

null

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

permissionsArray<string>

is_primarybooleanrequired

is_activebooleantrue

joined_atstringrequired

Example

{
  "id": "string",
  "user_id": "string",
  "tenant_id": "string",
  "tenant_name": "string",
  "role_id": "string",
  "role_name": "string",
  "permissions": [],
  "is_primary": true,
  "is_active": true,
  "joined_at": "string"
}

Backend_UserTenantListDto

object

DTO for listing user tenants

itemsArray<Backend_UserTenantDto>required

Show child attributes

DTO for user-tenant relationship

idstringrequired

user_idstringrequired

tenant_idstringrequired

tenant_namestring | null

Show child attributes

Any of

string

null

role_idstring | null

Show child attributes

Any of

string

null

role_namestring | null

Show child attributes

Any of

string

null

permissionsArray<string>

is_primarybooleanrequired

is_activebooleantrue

joined_atstringrequired

totalintegerrequired

skipinteger0

limitinteger10

has_nextbooleanfalse

has_previousbooleanfalse

Example

{
  "items": [
    {
      "id": "string",
      "user_id": "string",
      "tenant_id": "string",
      "tenant_name": "string",
      "role_id": "string",
      "role_name": "string",
      "permissions": [],
      "is_primary": true,
      "is_active": true,
      "joined_at": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 10,
  "has_next": false,
  "has_previous": false
}

Backend_UserTenantUpdateDto

object

DTO for updating user-tenant relationship

role_idstring | null

Show child attributes

Any of

string

null

is_primaryboolean | null

Show child attributes

Any of

boolean

null

is_activeboolean | null

Show child attributes

Any of

boolean

null

Backend_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

SurveyService_AddQuestionToSurveyRequest

object

question_idstringrequired

survey_idstringrequired

SurveyService_AddQuestionToSurveyResponse

object

survey_idstringrequired

question_idstringrequired

question_namestringrequired

questionobjectrequired

SurveyService_AvailableTriggersResponse

object

Response model for available trigger values with assignment info.

trigger_questionsArray<string>required

available_valuesobjectrequired

Show child attributes

[key: string]Array<string>

assigned_valuesobjectrequired

Show child attributes

[key: string]object

Show child attributes

[key: string]string | null

Show child attributes

Any of

string

null

SurveyService_BackfillAnchorSchema

object

Anchor configuration for timeline-aware backfill

typestringrequired

Anchor type

questionstring | null

Question name (for from_answer_month type)

Show child attributes

Any of

string

null

rule_idstring | null

Rule ID to anchor to (for before_rule/after_rule types)

Show child attributes

Any of

string

null

SurveyService_Body_import_questions_api_v1_surveys_question_bank_questions_import_post

object

filestringrequired

category_idstring | null

Show child attributes

Any of

string

null

SurveyService_Body_import_template_from_xlsform_api_v1_templates_import_xlsform_post

object

filestringrequired

XLSForm Excel file (.xlsx)

namestringrequired

Template name

category_idstringrequired

Template category ID

descriptionstring | null

Template description

Show child attributes

Any of

string

null

is_publicbooleanfalse

Whether the template is public

SurveyService_Body_import_xlsform_api_v1_surveys_import_xlsform_post

object

filestringrequired

XLSForm Excel file (.xlsx)

namestringrequired

Survey name

descriptionstring | null

Survey description

Show child attributes

Any of

string

null

project_idstring<uuid>required

Project ID from workspace-service

workspace_idstring<uuid>required

Workspace ID for the project

is_anonymousbooleanfalse

Whether responses are anonymous

allow_multiple_responsesbooleanfalse

Allow multiple responses per user

scheduling_enabledbooleanfalse

Enable survey scheduling (auto open/close)

open_atstring | null

Scheduled open timestamp (ISO 8601)

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Scheduled close timestamp (ISO 8601)

Show child attributes

Any of

string<date-time>

null

Example

{
  "file": "string",
  "name": "string",
  "description": "string",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "scheduling_enabled": false,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z"
}

SurveyService_Body_upload_survey_media_api_v1_surveys__survey_id__media_post

object

filestringrequired

ZIP file containing media assets

SurveyService_Body_upload_xlsform_as_new_version_api_v1_surveys__survey_id__versions_upload_post

object

filestringrequired

SurveyService_CalendarColumnSchema

object

Column definition for calendar_grid question type

keystringrequired

typestringselect_one

labelstring

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

choicesArray<object> | null

Choices for select_one type - name must be exactly 1 character

Show child attributes

Any of

Array<object>

null

relevantstring | null

Show child attributes

Any of

string

null

SurveyService_CalendarConfigSchema

object

Configuration for calendar_grid question type

modestringmonthly

months_backinteger[1, 120]12

start_fromstringtoday

allow_futurebooleanfalse

SurveyService_CalendarRuleSchema

object

Rule for auto-prefilling calendar column values

idstring | null

Unique rule ID

Show child attributes

Any of

string

null

trigger_questionstringrequired

Question name that triggers this rule

target_columnstringrequired

Calendar column key to fill

value_sourcestringconstant

Where to get the value: constant, lookup, or xpath expression

source_valuestring | null

Constant value to fill (for constant source)

Show child attributes

Any of

string

null

backfill_monthsinteger | null1

How many months to backfill from anchor

Show child attributes

Any of

integer[1, 120]

null

backfill_anchorstring | SurveyService_BackfillAnchorSchema | nullcurrent_month

Anchor for backfill: 'current_month', or anchor config object

Show child attributes

Any of

string

Anchor configuration for timeline-aware backfill

typestringrequired

Anchor type

questionstring | null

Question name (for from_answer_month type)

Show child attributes

Any of

string

null

rule_idstring | null

Rule ID to anchor to (for before_rule/after_rule types)

Show child attributes

Any of

string

null

map_valuesobject | null

Map trigger values to calendar values (e.g., {'yes': 'Y', 'no': 'N'})

Show child attributes

Any of

[key: string]string

null

xpath_expressionstring | null

XPath expression to calculate value (for xpath source)

Show child attributes

Any of

string

null

enabledbooleantrue

Whether rule is active

conditionsArray<object> | null

Conditions for when the rule applies (Visual Rule Builder)

Show child attributes

Any of

Array<object>

null

months_scopeobject | null

Months scope configuration for the rule

Show child attributes

Any of

object

null

Example

{
  "id": "string",
  "trigger_question": "string",
  "target_column": "string",
  "value_source": "constant",
  "source_value": "string",
  "backfill_months": 1,
  "backfill_anchor": "current_month",
  "map_values": {},
  "xpath_expression": "string",
  "enabled": true,
  "conditions": [
    {}
  ],
  "months_scope": {}
}

SurveyService_ChoiceSchema

object

Choice list item (XLSForm choices sheet)

list_namestringrequired

namestringrequired

labelstringrequired

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

media_filestring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

SurveyService_CollectionGrantResponse

object

idstringrequired

kindstringrequired

survey_idstringrequired

survey_version_idstringrequired

user_idstringrequired

device_idstring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

project_status_at_issuestringrequired

granted_atstring | null

Show child attributes

Any of

string

null

project_boundbooleantrue

Example

{
  "id": "string",
  "kind": "string",
  "survey_id": "string",
  "survey_version_id": "string",
  "user_id": "string",
  "device_id": "string",
  "interview_id": "string",
  "project_status_at_issue": "string",
  "granted_at": "string",
  "project_bound": true
}

SurveyService_CreateSurveyFromTemplateRequest

object

template_idstringrequired

Template ID to create survey from

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

workspace_idstringrequired

Workspace ID for the new survey

project_idstringrequired

Project ID for the new survey

is_anonymousbooleanfalse

allow_multiple_responsesbooleanfalse

scheduling_enabledbooleanfalse

open_atstring | null

Scheduled open timestamp

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Scheduled close timestamp

Show child attributes

Any of

string<date-time>

null

Example

{
  "template_id": "string",
  "name": "string",
  "description": "string",
  "workspace_id": "string",
  "project_id": "string",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "scheduling_enabled": false,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z"
}

SurveyService_CreateSurveyFromTemplateResponse

object

survey_idstringrequired

namestringrequired

template_idstringrequired

created_atstring<date-time>required

SurveyService_EnumeratorListResponse

object

enumerator_idsArray<string>required

SurveyService_ExpressionValidationError

object

A single validation error for expression validation.

fieldstringrequired

messagestringrequired

codestringrequired

contextobject | null

Show child attributes

Any of

object

null

SurveyService_ExpressionValidationRequest

object

Request body for expression validation endpoint.

expressionstringrequired

The expression to validate (XPath format with ${field_name} references)

expression_typestringrelevant

Type of expression being validated

available_fieldsArray<string>

List of available question/field names for reference validation

SurveyService_ExpressionValidationResponse

object

Response from expression validation endpoint.

is_validbooleanrequired

expressionstringrequired

expression_typestringrequired

errorsArray<SurveyService_ExpressionValidationError>

Show child attributes

A single validation error for expression validation.

fieldstringrequired

messagestringrequired

codestringrequired

contextobject | null

Show child attributes

Any of

object

null

Example

{
  "is_valid": true,
  "expression": "string",
  "expression_type": "string",
  "errors": [
    {
      "field": "string",
      "message": "string",
      "code": "string",
      "context": {}
    }
  ]
}

SurveyService_FormAccessBulkCreate

object

user_idsArray<string>required

access_levelSurveyService_FormAccessLevelfillview_onlyapproverfill

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

assigned_triggersArray<SurveyService_LookupTriggerAssignment> | null

Show child attributes

Any of

Array<SurveyService_LookupTriggerAssignment>

Show child attributes

A single trigger value assignment for an enumerator.

trigger_questionstringrequired

Name of the trigger question, e.g., 's_state'

trigger_valuestringrequired

Value of the trigger, e.g., 'rajasthan'

null

Example

{
  "user_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}

SurveyService_FormAccessCheckResponse

object

has_accessbooleanrequired

access_levelstring | null

Show child attributes

Any of

string

null

can_fillbooleanfalse

can_viewbooleanfalse

can_approvebooleanfalse

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

is_openbooleantrue

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_blocked_reasonstring | null

Show child attributes

Any of

string

null

Example

{
  "has_access": true,
  "access_level": "string",
  "can_fill": false,
  "can_view": false,
  "can_approve": false,
  "expires_at": "2024-01-15T09:30:00Z",
  "is_open": true,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_blocked_reason": "string"
}

SurveyService_FormAccessCreate

object

user_idstring<uuid>required

access_levelSurveyService_FormAccessLevelfillview_onlyapproverfill

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

assigned_triggersArray<SurveyService_LookupTriggerAssignment> | null

Show child attributes

Any of

Array<SurveyService_LookupTriggerAssignment>

Show child attributes

A single trigger value assignment for an enumerator.

trigger_questionstringrequired

Name of the trigger question, e.g., 's_state'

trigger_valuestringrequired

Value of the trigger, e.g., 'rajasthan'

null

Example

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "fill",
  "expires_at": "2024-01-15T09:30:00Z",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}

SurveyService_FormAccessLevel

string

SurveyService_FormAccessLevelfillview_onlyapprover

SurveyService_FormAccessListResponse

object

itemsArray<SurveyService_FormAccessWithUserResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

survey_idstring<uuid>required

user_idstring<uuid>required

granted_bystring<uuid>required

access_levelstringrequired

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

revoked_atstring | null

Show child attributes

Any of

string<date-time>

null

revoked_bystring | null

Show child attributes

Any of

string<uuid>

null

revocation_reasonstring | null

Show child attributes

Any of

string

null

user_emailstring | null

Show child attributes

Any of

string

null

user_first_namestring | null

Show child attributes

Any of

string

null

user_last_namestring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

user_rolestring | null

Show child attributes

Any of

string

null

assigned_triggersArray<SurveyService_LookupTriggerAssignment> | null

Show child attributes

Any of

Array<SurveyService_LookupTriggerAssignment>

Show child attributes

A single trigger value assignment for an enumerator.

trigger_questionstringrequired

Name of the trigger question, e.g., 's_state'

trigger_valuestringrequired

Value of the trigger, e.g., 'rajasthan'

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "granted_by": "550e8400-e29b-41d4-a716-446655440000",
      "access_level": "string",
      "expires_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "revoked_at": "2024-01-15T09:30:00Z",
      "revoked_by": "550e8400-e29b-41d4-a716-446655440000",
      "revocation_reason": "string",
      "user_email": "string",
      "user_first_name": "string",
      "user_last_name": "string",
      "user_code": "string",
      "user_role": "string",
      "assigned_triggers": [
        {
          "trigger_question": "string",
          "trigger_value": "string"
        }
      ]
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

SurveyService_FormAccessResponse

object

idstring<uuid>required

tenant_idstring<uuid>required

survey_idstring<uuid>required

user_idstring<uuid>required

granted_bystring<uuid>required

access_levelstringrequired

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

revoked_atstring | null

Show child attributes

Any of

string<date-time>

null

revoked_bystring | null

Show child attributes

Any of

string<uuid>

null

revocation_reasonstring | null

Show child attributes

Any of

string

null

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "granted_by": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "string",
  "expires_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "revoked_at": "2024-01-15T09:30:00Z",
  "revoked_by": "550e8400-e29b-41d4-a716-446655440000",
  "revocation_reason": "string"
}

SurveyService_FormAccessRevokeRequest

object

reasonstring | null

Auditable reason for revocation

Show child attributes

Any of

string

null

SurveyService_FormAccessRevokeResponse

object

messagestringrequired

user_idstring<uuid>required

survey_idstring<uuid>required

grant_idstring<uuid>required

revoked_atstring<date-time>required

revoked_bystring<uuid>required

revocation_reasonstring | null

Show child attributes

Any of

string

null

Example

{
  "message": "string",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "revoked_at": "2024-01-15T09:30:00Z",
  "revoked_by": "550e8400-e29b-41d4-a716-446655440000",
  "revocation_reason": "string"
}

SurveyService_FormAccessUpdate

object

access_levelSurveyService_FormAccessLevel | null

Show child attributes

Any of

SurveyService_FormAccessLevelfillview_onlyapprover

null

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

assigned_triggersArray<SurveyService_LookupTriggerAssignment> | null

Show child attributes

Any of

Array<SurveyService_LookupTriggerAssignment>

Show child attributes

A single trigger value assignment for an enumerator.

trigger_questionstringrequired

Name of the trigger question, e.g., 's_state'

trigger_valuestringrequired

Value of the trigger, e.g., 'rajasthan'

null

SurveyService_FormAccessWithUserResponse

object

idstring<uuid>required

tenant_idstring<uuid>required

survey_idstring<uuid>required

user_idstring<uuid>required

granted_bystring<uuid>required

access_levelstringrequired

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

revoked_atstring | null

Show child attributes

Any of

string<date-time>

null

revoked_bystring | null

Show child attributes

Any of

string<uuid>

null

revocation_reasonstring | null

Show child attributes

Any of

string

null

user_emailstring | null

Show child attributes

Any of

string

null

user_first_namestring | null

Show child attributes

Any of

string

null

user_last_namestring | null

Show child attributes

Any of

string

null

user_codestring | null

Show child attributes

Any of

string

null

user_rolestring | null

Show child attributes

Any of

string

null

assigned_triggersArray<SurveyService_LookupTriggerAssignment> | null

Show child attributes

Any of

Array<SurveyService_LookupTriggerAssignment>

Show child attributes

A single trigger value assignment for an enumerator.

trigger_questionstringrequired

Name of the trigger question, e.g., 's_state'

trigger_valuestringrequired

Value of the trigger, e.g., 'rajasthan'

null

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "granted_by": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "string",
  "expires_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "revoked_at": "2024-01-15T09:30:00Z",
  "revoked_by": "550e8400-e29b-41d4-a716-446655440000",
  "revocation_reason": "string",
  "user_email": "string",
  "user_first_name": "string",
  "user_last_name": "string",
  "user_code": "string",
  "user_role": "string",
  "assigned_triggers": [
    {
      "trigger_question": "string",
      "trigger_value": "string"
    }
  ]
}

SurveyService_HTTPValidationError

object

detailArray<SurveyService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

SurveyService_HealthResponseDTO

object

Health check response model.

statusstringrequired

servicestringrequired

versionstringrequired

timestampstring<date-time>required

SurveyService_HistoricalAccessCheckResponse

object

has_accessbooleanrequired

grant_idstring | null

Show child attributes

Any of

string<uuid>

null

access_levelstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string<date-time>

null

revoked_atstring | null

Show child attributes

Any of

string<date-time>

null

revocation_reasonstring | null

Show child attributes

Any of

string

null

is_revokedbooleanfalse

Example

{
  "has_access": true,
  "grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "access_level": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "revoked_at": "2024-01-15T09:30:00Z",
  "revocation_reason": "string",
  "is_revoked": false
}

SurveyService_IssueCollectionGrantRequest

object

kindstringrequired

device_download | interview_reservation

user_idstring<uuid>required

survey_version_idstring<uuid>required

device_idstring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string<uuid>

null

schema_hashstring | null

Show child attributes

Any of

string

null

Example

{
  "kind": "string",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema_hash": "string"
}

SurveyService_LanguageCreate

object

codestringrequired

Language code (e.g., 'en', 'hi')

namestringrequired

Language name (e.g., 'English', 'Hindi')

flag_emojistring | null

Flag emoji (e.g., '🇺🇸')

Show child attributes

Any of

string

null

is_activebooleantrue

Whether language is active

display_orderinteger0

Display order for sorting

SurveyService_LanguageListResponse

object

languagesArray<SurveyService_LanguageResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

codestringrequired

namestringrequired

flag_emojistring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

display_orderintegerrequired

totalintegerrequired

Example

{
  "languages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "string",
      "name": "string",
      "flag_emoji": "string",
      "is_active": true,
      "display_order": 0
    }
  ],
  "total": 0
}

SurveyService_LanguageReorderRequest

object

language_idsArray<string>required

List of language codes in desired order

SurveyService_LanguageResponse

object

idstring<uuid>required

tenant_idstring<uuid>required

codestringrequired

namestringrequired

flag_emojistring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

display_orderintegerrequired

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "string",
  "name": "string",
  "flag_emoji": "string",
  "is_active": true,
  "display_order": 0
}

SurveyService_LanguageUpdate

object

codestring | null

Show child attributes

Any of

string

null

namestring | null

Show child attributes

Any of

string

null

flag_emojistring | null

Show child attributes

Any of

string

null

is_activeboolean | null

Show child attributes

Any of

boolean

null

display_orderinteger | null

Show child attributes

Any of

integer

null

SurveyService_LimitSchema

object

Limit configuration for text/number fields. For text: min/max character count For integer/decimal: min/max value

mininteger | null

Show child attributes

Any of

integer

null

maxinteger | null

Show child attributes

Any of

integer

null

SurveyService_LookupConfigResponse

object

Response model for lookup configuration.

has_lookupsbooleanrequired

lookup_keysArray<object>required

trigger_questionsArray<string>required

referee_questionsobjectrequired

Show child attributes

[key: string]Array<string>

SurveyService_LookupResolveRequest

object

Request model for lookup resolution.

trigger_questionstringrequired

Name of the trigger question

trigger_valuestringrequired

Selected value for the trigger question

current_valuesobject | null

Current values of all questions (for change detection)

Show child attributes

Any of

object

null

SurveyService_LookupResolveResponse

object

Response model for lookup resolution.

trigger_questionstringrequired

trigger_valuestringrequired

resolved_valuesobjectrequired

fields_to_clearArray<string>

is_validbooleantrue

error_messagestring | null

Show child attributes

Any of

string

null

SurveyService_LookupResponse

object

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

SurveyService_LookupSchema

object

Lookup data item (custom lookups worksheet). Used for cascading selects and external data lookups.

Example:

lookup_name: "countries" or "states"
key: "us" or "ny"
value: "United States" or "New York"
parent_key: None for countries, "us" for states (cascading)
extra_data: {"code": "USA", "region": "north_america"}

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

SurveyService_LookupStatisticsResponse

object

Response model for lookup statistics.

trigger_questionsintegerrequired

total_valuesintegerrequired

trigger_detailsobjectrequired

Show child attributes

[key: string]object

SurveyService_LookupTriggerAssignment

object

A single trigger value assignment for an enumerator.

trigger_questionstringrequired

Name of the trigger question, e.g., 's_state'

trigger_valuestringrequired

Value of the trigger, e.g., 'rajasthan'

SurveyService_LookupValidateRequest

object

Request model for lookup validation.

trigger_questionstringrequired

Name of the trigger question

trigger_valuestringrequired

Value to validate

SurveyService_LookupValidateResponse

object

Response model for lookup validation.

is_validbooleanrequired

trigger_questionstringrequired

trigger_valuestringrequired

error_messagestring | null

Show child attributes

Any of

string

null

available_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

SurveyService_QuestionBankCategoryCreate

object

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

SurveyService_QuestionBankCategoryListResponse

object

itemsArray<SurveyService_QuestionBankCategoryResponse>required

Show child attributes

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

question_countinteger0

created_atstring<date-time>required

updated_atstring<date-time>required

totalintegerrequired

limitintegerrequired

skipintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "name": "string",
      "description": "string",
      "color": "string",
      "question_count": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "skip": 0,
  "has_next": true,
  "has_previous": true
}

SurveyService_QuestionBankCategoryResponse

object

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

question_countinteger0

created_atstring<date-time>required

updated_atstring<date-time>required

Example

{
  "id": "string",
  "tenant_id": "string",
  "name": "string",
  "description": "string",
  "color": "string",
  "question_count": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

SurveyService_QuestionBankCategoryUpdate

object

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

SurveyService_QuestionBulkImportResponse

object

totalintegerrequired

createdintegerrequired

failedintegerrequired

errorsArray<SurveyService_QuestionImportRowError>

Show child attributes

rowintegerrequired

fieldstring

codestringrequired

messagestringrequired

SurveyService_QuestionCreate

object

category_idstring | null

Show child attributes

Any of

string

null

question_typestringrequired

namestringrequired

labelstring

label_translationsobject

Show child attributes

[key: string]string

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject

Show child attributes

[key: string]string

requiredbooleanfalse

question_configobject

tagsArray<string>

is_publicbooleanfalse

Example

{
  "category_id": "string",
  "question_type": "string",
  "name": "string",
  "label": "",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": false,
  "question_config": {},
  "tags": [
    "string"
  ],
  "is_public": false
}

SurveyService_QuestionImportRowError

object

rowintegerrequired

fieldstring

codestringrequired

messagestringrequired

SurveyService_QuestionListResponse

object

itemsArray<SurveyService_QuestionResponse>required

Show child attributes

idstringrequired

tenant_idstringrequired

category_idstring | null

Show child attributes

Any of

string

null

question_typestringrequired

namestringrequired

labelstringrequired

label_translationsobjectrequired

Show child attributes

[key: string]string

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobjectrequired

Show child attributes

[key: string]string

requiredbooleanrequired

question_configobjectrequired

tagsArray<string>required

usage_countintegerrequired

is_publicbooleanrequired

created_bystringrequired

updated_bystring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_QuestionBankCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

question_countinteger0

created_atstring<date-time>required

updated_atstring<date-time>required

null

totalintegerrequired

limitintegerrequired

skipintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "category_id": "string",
      "question_type": "string",
      "name": "string",
      "label": "string",
      "label_translations": {},
      "hint": "string",
      "hint_translations": {},
      "required": true,
      "question_config": {},
      "tags": [
        "string"
      ],
      "usage_count": 0,
      "is_public": true,
      "created_by": "string",
      "updated_by": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "category": {
        "id": "string",
        "tenant_id": "string",
        "name": "string",
        "description": "string",
        "color": "string",
        "question_count": 0,
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    }
  ],
  "total": 0,
  "limit": 0,
  "skip": 0,
  "has_next": true,
  "has_previous": true
}

SurveyService_QuestionResponse

object

idstringrequired

tenant_idstringrequired

category_idstring | null

Show child attributes

Any of

string

null

question_typestringrequired

namestringrequired

labelstringrequired

label_translationsobjectrequired

Show child attributes

[key: string]string

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobjectrequired

Show child attributes

[key: string]string

requiredbooleanrequired

question_configobjectrequired

tagsArray<string>required

usage_countintegerrequired

is_publicbooleanrequired

created_bystringrequired

updated_bystring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_QuestionBankCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

question_countinteger0

created_atstring<date-time>required

updated_atstring<date-time>required

null

Example

{
  "id": "string",
  "tenant_id": "string",
  "category_id": "string",
  "question_type": "string",
  "name": "string",
  "label": "string",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": true,
  "question_config": {},
  "tags": [
    "string"
  ],
  "usage_count": 0,
  "is_public": true,
  "created_by": "string",
  "updated_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "color": "string",
    "question_count": 0,
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
}

SurveyService_QuestionUpdate

object

category_idstring | null

Show child attributes

Any of

string

null

labelstring | null

Show child attributes

Any of

string

null

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredboolean | null

Show child attributes

Any of

boolean

null

question_configobject | null

Show child attributes

Any of

object

null

tagsArray<string> | null

Show child attributes

Any of

Array<string>

null

is_publicboolean | null

Show child attributes

Any of

boolean

null

Example

{
  "category_id": "string",
  "label": "string",
  "label_translations": {},
  "hint": "string",
  "hint_translations": {},
  "required": true,
  "question_config": {},
  "tags": [
    "string"
  ],
  "is_public": true
}

SurveyService_SettingsSchema

object

Survey-level settings (XLSForm settings sheet)

form_titlestringrequired

form_idstring | null

Show child attributes

Any of

string

null

versionstring | null

Show child attributes

Any of

string

null

defaultLanguagestring | nullen

Show child attributes

Any of

string

null

languagesArray<string> | null

Show child attributes

Any of

Array<string>

null

availableLanguagesArray<string> | null

Show child attributes

Any of

Array<string>

null

instanceNamestring | null

Show child attributes

Any of

string

null

submissionUrlstring | null

Show child attributes

Any of

string

null

Example

{
  "form_title": "string",
  "form_id": "string",
  "version": "string",
  "defaultLanguage": "en",
  "languages": [
    "string"
  ],
  "availableLanguages": [
    "string"
  ],
  "instanceName": "string",
  "submissionUrl": "string"
}

SurveyService_SurveyAccessListResponse

object

itemsArray<SurveyService_SurveyWithAccessResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

statusstringrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

versionstring | null

Show child attributes

Any of

string

null

access_levelstringrequired

can_fillbooleanrequired

can_viewbooleanrequired

can_approvebooleanfalse

created_atstring<date-time>required

updated_atstring | null

Show child attributes

Any of

string<date-time>

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "status": "string",
      "survey_code": 0,
      "version": "string",
      "access_level": "string",
      "can_fill": true,
      "can_view": true,
      "can_approve": false,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

SurveyService_SurveyCreate

object

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

is_anonymousbooleanfalse

allow_multiple_responsesbooleanfalse

schemaSurveyService_SurveySchema | null

Show child attributes

Any of

Complete XLSForm-compatible survey schema. Stored in JSONB column in survey_versions table. Includes support for custom lookups worksheet for cascading selects.

settingsSurveyService_SettingsSchemarequired

Survey-level settings (XLSForm settings sheet)

Show child attributes

form_titlestringrequired

form_idstring | null

Show child attributes

Any of

string

null

versionstring | null

Show child attributes

Any of

string

null

defaultLanguagestring | nullen

Show child attributes

Any of

string

null

languagesArray<string> | null

Show child attributes

Any of

Array<string>

null

availableLanguagesArray<string> | null

Show child attributes

Any of

Array<string>

null

instanceNamestring | null

Show child attributes

Any of

string

null

submissionUrlstring | null

Show child attributes

Any of

string

null

choicesArray<SurveyService_ChoiceSchema>

Show child attributes

Choice list item (XLSForm choices sheet)

list_namestringrequired

namestringrequired

labelstringrequired

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

media_filestring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionSchema>required

Show child attributes

XLSForm-compatible question schema. Supports all 22 question types with recursive nesting for groups/repeats.

Complete XLSForm-compatible question types (KoboToolbox standard). Reference: https://xlsform.org/en/#question-types

namestringrequired

labelstring

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

hintTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraintMessageTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | null

Show child attributes

Any of

string

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionSchema> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionSchema>

null

calendar_configSurveyService_CalendarConfigSchema | null

Show child attributes

Any of

Configuration for calendar_grid question type

modestringmonthly

months_backinteger[1, 120]12

start_fromstringtoday

allow_futurebooleanfalse

null

calendar_rulesArray<SurveyService_CalendarRuleSchema> | null

Auto-prefill rules for calendar columns

Show child attributes

Any of

Array<SurveyService_CalendarRuleSchema>

Show child attributes

Rule for auto-prefilling calendar column values

idstring | null

Unique rule ID

Show child attributes

Any of

string

null

trigger_questionstringrequired

Question name that triggers this rule

target_columnstringrequired

Calendar column key to fill

value_sourcestringconstant

Where to get the value: constant, lookup, or xpath expression

source_valuestring | null

Constant value to fill (for constant source)

Show child attributes

Any of

string

null

backfill_monthsinteger | null1

How many months to backfill from anchor

Show child attributes

Any of

integer[1, 120]

null

backfill_anchorstring | SurveyService_BackfillAnchorSchema | nullcurrent_month

Anchor for backfill: 'current_month', or anchor config object

Show child attributes

Any of

string

Anchor configuration for timeline-aware backfill

typestringrequired

Anchor type

questionstring | null

Question name (for from_answer_month type)

Show child attributes

Any of

Max depth reached

rule_idstring | null

Rule ID to anchor to (for before_rule/after_rule types)

Show child attributes

Any of

Max depth reached

null

map_valuesobject | null

Map trigger values to calendar values (e.g., {'yes': 'Y', 'no': 'N'})

Show child attributes

Any of

[key: string]string

null

xpath_expressionstring | null

XPath expression to calculate value (for xpath source)

Show child attributes

Any of

string

null

enabledbooleantrue

Whether rule is active

conditionsArray<object> | null

Conditions for when the rule applies (Visual Rule Builder)

Show child attributes

Any of

Array<object>

null

months_scopeobject | null

Months scope configuration for the rule

Show child attributes

Any of

object

null

columnsArray<SurveyService_CalendarColumnSchema> | null

Show child attributes

Any of

Array<SurveyService_CalendarColumnSchema>

Show child attributes

Column definition for calendar_grid question type

keystringrequired

typestringselect_one

labelstring

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

choicesArray<object> | null

Choices for select_one type - name must be exactly 1 character

Show child attributes

Any of

Array<object>

null

relevantstring | null

Show child attributes

Any of

string

null

limitSurveyService_LimitSchema | null

Show child attributes

Any of

Limit configuration for text/number fields. For text: min/max character count For integer/decimal: min/max value

mininteger | null

Show child attributes

Any of

integer

null

maxinteger | null

Show child attributes

Any of

integer

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

mediaAudiostring | null

Show child attributes

Any of

string

null

mediaAudioSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioUrlstring | null

Show child attributes

Any of

string

null

mediaAudioAssetIdstring | null

Show child attributes

Any of

string

null

mediaAudioUrlSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioAssetIdSchemaobject | null

Show child attributes

Any of

[key: string]string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

lookupsArray<SurveyService_LookupSchema>

Show child attributes

Lookup data item (custom lookups worksheet). Used for cascading selects and external data lookups.

Example:

lookup_name: "countries" or "states"
key: "us" or "ny"
value: "United States" or "New York"
parent_key: None for countries, "us" for states (cascading)
extra_data: {"code": "USA", "region": "north_america"}

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

Example

{
  "name": "string",
  "description": "string",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_anonymous": false,
  "allow_multiple_responses": false,
  "schema": {
    "settings": {
      "form_title": "string",
      "form_id": "string",
      "version": "string",
      "defaultLanguage": "en",
      "languages": [
        "string"
      ],
      "availableLanguages": [
        "string"
      ],
      "instanceName": "string",
      "submissionUrl": "string"
    },
    "choices": [
      {
        "list_name": "string",
        "name": "string",
        "label": "string",
        "labelTranslations": {},
        "media_file": "string",
        "constraint": "string"
      }
    ],
    "questions": [
      {
        "type": "text",
        "name": "string",
        "label": "",
        "required": false,
        "hint": "string",
        "labelTranslations": {},
        "hintTranslations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraintMessageTranslations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "calendar_config": {
          "mode": "monthly",
          "months_back": 12,
          "start_from": "today",
          "allow_future": false
        },
        "calendar_rules": [
          {
            "id": "string",
            "trigger_question": "string",
            "target_column": "string",
            "value_source": "constant",
            "source_value": "string",
            "backfill_months": 1,
            "backfill_anchor": "current_month",
            "map_values": {},
            "xpath_expression": "string",
            "enabled": true,
            "conditions": [
              {}
            ],
            "months_scope": {}
          }
        ],
        "columns": [
          {
            "key": "string",
            "type": "select_one",
            "label": "",
            "label_translations": {},
            "choices": [
              {}
            ],
            "relevant": "string"
          }
        ],
        "limit": {
          "min": 0,
          "max": 0
        },
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "mediaAudio": "string",
        "mediaAudioSchema": {},
        "mediaAudioUrl": "string",
        "mediaAudioAssetId": "string",
        "mediaAudioUrlSchema": {},
        "mediaAudioAssetIdSchema": {},
        "deidentify": false,
        "unique_id": false,
        "lookups": "string"
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false
}

SurveyService_SurveyListResponse

object

itemsArray<SurveyService_SurveyResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

totalintegerrequired

limitintegerrequired

skipintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "description": "string",
      "status": "string",
      "is_anonymous": true,
      "allow_multiple_responses": true,
      "survey_code": 0,
      "tags": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "string",
          "color": "string",
          "created_at": "2024-01-15T09:30:00Z",
          "updated_at": "2024-01-15T09:30:00Z",
          "created_by": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000",
      "closed_at": "2024-01-15T09:30:00Z",
      "open_at": "2024-01-15T09:30:00Z",
      "close_at": "2024-01-15T09:30:00Z",
      "scheduling_enabled": false,
      "is_open": false,
      "schema": {
        "settings": {},
        "choices": [
          {}
        ],
        "questions": [
          {
            "type": "string",
            "name": "string",
            "label": "string",
            "label_translations": {},
            "required": false,
            "hint": "string",
            "hint_translations": {},
            "default": "string",
            "order_index": 0,
            "additional_values": [
              "string"
            ],
            "read_only": false,
            "appearance": "string",
            "relevant": "string",
            "constraint": "string",
            "constraint_message": "string",
            "constraint_message_translations": {},
            "calculation": "string",
            "choices": "string",
            "choice_filter": "string",
            "choice_relation": "string",
            "repeat_count": "string",
            "questions": [],
            "limit": {},
            "paradata": [
              "string"
            ],
            "media_file": "string",
            "deidentify": false,
            "unique_id": false,
            "lookups": "string",
            "calendar_config": {},
            "calendar_rules": [
              {}
            ],
            "columns": [
              {}
            ]
          }
        ],
        "lookups": [
          {
            "lookup_name": "string",
            "key": "string",
            "value": "string",
            "parent_key": "string",
            "extra_data": {}
          }
        ],
        "lookup_data": [
          {}
        ]
      },
      "project_status": "string",
      "project_has_production_activity": true,
      "project_production_activity_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "skip": 0,
  "has_next": true,
  "has_previous": true
}

SurveyService_SurveyQuestionResponse

object

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

Example

{
  "type": "string",
  "name": "string",
  "label": "string",
  "label_translations": {},
  "required": false,
  "hint": "string",
  "hint_translations": {},
  "default": "string",
  "order_index": 0,
  "additional_values": [
    "string"
  ],
  "read_only": false,
  "appearance": "string",
  "relevant": "string",
  "constraint": "string",
  "constraint_message": "string",
  "constraint_message_translations": {},
  "calculation": "string",
  "choices": "string",
  "choice_filter": "string",
  "choice_relation": "string",
  "repeat_count": "string",
  "questions": [],
  "limit": {},
  "paradata": [
    "string"
  ],
  "media_file": "string",
  "deidentify": false,
  "unique_id": false,
  "lookups": "string",
  "calendar_config": {},
  "calendar_rules": [
    {}
  ],
  "columns": [
    {}
  ]
}

SurveyService_SurveyQuestionSchema

object

XLSForm-compatible question schema. Supports all 22 question types with recursive nesting for groups/repeats.

Complete XLSForm-compatible question types (KoboToolbox standard). Reference: https://xlsform.org/en/#question-types

namestringrequired

labelstring

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

hintTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraintMessageTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | null

Show child attributes

Any of

string

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionSchema> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionSchema>

null

calendar_configSurveyService_CalendarConfigSchema | null

Show child attributes

Any of

Configuration for calendar_grid question type

modestringmonthly

months_backinteger[1, 120]12

start_fromstringtoday

allow_futurebooleanfalse

null

calendar_rulesArray<SurveyService_CalendarRuleSchema> | null

Auto-prefill rules for calendar columns

Show child attributes

Any of

Array<SurveyService_CalendarRuleSchema>

Show child attributes

Rule for auto-prefilling calendar column values

idstring | null

Unique rule ID

Show child attributes

Any of

string

null

trigger_questionstringrequired

Question name that triggers this rule

target_columnstringrequired

Calendar column key to fill

value_sourcestringconstant

Where to get the value: constant, lookup, or xpath expression

source_valuestring | null

Constant value to fill (for constant source)

Show child attributes

Any of

string

null

backfill_monthsinteger | null1

How many months to backfill from anchor

Show child attributes

Any of

integer[1, 120]

null

backfill_anchorstring | SurveyService_BackfillAnchorSchema | nullcurrent_month

Anchor for backfill: 'current_month', or anchor config object

Show child attributes

Any of

string

Anchor configuration for timeline-aware backfill

typestringrequired

Anchor type

questionstring | null

Question name (for from_answer_month type)

Show child attributes

Any of

string

null

rule_idstring | null

Rule ID to anchor to (for before_rule/after_rule types)

Show child attributes

Any of

string

null

map_valuesobject | null

Map trigger values to calendar values (e.g., {'yes': 'Y', 'no': 'N'})

Show child attributes

Any of

[key: string]string

null

xpath_expressionstring | null

XPath expression to calculate value (for xpath source)

Show child attributes

Any of

string

null

enabledbooleantrue

Whether rule is active

conditionsArray<object> | null

Conditions for when the rule applies (Visual Rule Builder)

Show child attributes

Any of

Array<object>

null

months_scopeobject | null

Months scope configuration for the rule

Show child attributes

Any of

object

null

columnsArray<SurveyService_CalendarColumnSchema> | null

Show child attributes

Any of

Array<SurveyService_CalendarColumnSchema>

Show child attributes

Column definition for calendar_grid question type

keystringrequired

typestringselect_one

labelstring

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

choicesArray<object> | null

Choices for select_one type - name must be exactly 1 character

Show child attributes

Any of

Array<object>

null

relevantstring | null

Show child attributes

Any of

string

null

limitSurveyService_LimitSchema | null

Show child attributes

Any of

Limit configuration for text/number fields. For text: min/max character count For integer/decimal: min/max value

mininteger | null

Show child attributes

Any of

integer

null

maxinteger | null

Show child attributes

Any of

integer

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

mediaAudiostring | null

Show child attributes

Any of

string

null

mediaAudioSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioUrlstring | null

Show child attributes

Any of

string

null

mediaAudioAssetIdstring | null

Show child attributes

Any of

string

null

mediaAudioUrlSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioAssetIdSchemaobject | null

Show child attributes

Any of

[key: string]string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

Example

{
  "type": "text",
  "name": "string",
  "label": "",
  "required": false,
  "hint": "string",
  "labelTranslations": {},
  "hintTranslations": {},
  "default": "string",
  "order_index": 0,
  "additional_values": [
    "string"
  ],
  "read_only": false,
  "appearance": "string",
  "relevant": "string",
  "constraint": "string",
  "constraint_message": "string",
  "constraintMessageTranslations": {},
  "calculation": "string",
  "choices": "string",
  "choice_filter": "string",
  "choice_relation": "string",
  "repeat_count": "string",
  "questions": [],
  "calendar_config": {
    "mode": "monthly",
    "months_back": 12,
    "start_from": "today",
    "allow_future": false
  },
  "calendar_rules": [
    {
      "id": "string",
      "trigger_question": "string",
      "target_column": "string",
      "value_source": "constant",
      "source_value": "string",
      "backfill_months": 1,
      "backfill_anchor": "current_month",
      "map_values": {},
      "xpath_expression": "string",
      "enabled": true,
      "conditions": [
        {}
      ],
      "months_scope": {}
    }
  ],
  "columns": [
    {
      "key": "string",
      "type": "select_one",
      "label": "",
      "label_translations": {},
      "choices": [
        {}
      ],
      "relevant": "string"
    }
  ],
  "limit": {
    "min": 0,
    "max": 0
  },
  "paradata": [
    "string"
  ],
  "media_file": "string",
  "mediaAudio": "string",
  "mediaAudioSchema": {},
  "mediaAudioUrl": "string",
  "mediaAudioAssetId": "string",
  "mediaAudioUrlSchema": {},
  "mediaAudioAssetIdSchema": {},
  "deidentify": false,
  "unique_id": false,
  "lookups": "string"
}

SurveyService_SurveyQuestionType

string

Complete XLSForm-compatible question types (KoboToolbox standard). Reference: https://xlsform.org/en/#question-types

SurveyService_SurveyQuestionTypetextintegerdecimalrangeselect_oneselect_multiplerankdatetimedatetimegeopointgeotracegeoshapeimageaudiovideofilebarcodesignaturecalculatenotehiddenacknowledgetriggerurlphonestartendtodaydeviceidphonenumberusernameemailsimserialsubscriberidauditxml-externalcsv-externalbegin_groupend_groupbegin_repeatend_repeatcalendar_grid

SurveyService_SurveyResponse

object

idstring<uuid>required

tenant_idstring<uuid>required

workspace_idstring | null

Show child attributes

Any of

string<uuid>

null

project_idstring<uuid>required

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_anonymousbooleanrequired

allow_multiple_responsesbooleanrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

tagsArray<SurveyService_TagResponse>

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

closed_atstring | null

Show child attributes

Any of

string<date-time>

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleanfalse

is_openbooleanfalse

schemaSurveyService_SurveySchemaResponse | null

Show child attributes

Any of

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

project_statusstring | null

Show child attributes

Any of

string

null

project_has_production_activityboolean | null

Show child attributes

Any of

boolean

null

project_production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "survey_code": 0,
  "tags": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000",
  "closed_at": "2024-01-15T09:30:00Z",
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": false,
  "is_open": false,
  "schema": {
    "settings": {},
    "choices": [
      {}
    ],
    "questions": [
      {
        "type": "string",
        "name": "string",
        "label": "string",
        "label_translations": {},
        "required": false,
        "hint": "string",
        "hint_translations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraint_message_translations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "limit": {},
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "deidentify": false,
        "unique_id": false,
        "lookups": "string",
        "calendar_config": {},
        "calendar_rules": [
          {}
        ],
        "columns": [
          {}
        ]
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "project_status": "string",
  "project_has_production_activity": true,
  "project_production_activity_at": "2024-01-15T09:30:00Z"
}

SurveyService_SurveyScheduleRequest

object

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledbooleantrue

SurveyService_SurveySchema

object

Complete XLSForm-compatible survey schema. Stored in JSONB column in survey_versions table. Includes support for custom lookups worksheet for cascading selects.

settingsSurveyService_SettingsSchemarequired

Survey-level settings (XLSForm settings sheet)

Show child attributes

form_titlestringrequired

form_idstring | null

Show child attributes

Any of

string

null

versionstring | null

Show child attributes

Any of

string

null

defaultLanguagestring | nullen

Show child attributes

Any of

string

null

languagesArray<string> | null

Show child attributes

Any of

Array<string>

null

availableLanguagesArray<string> | null

Show child attributes

Any of

Array<string>

null

instanceNamestring | null

Show child attributes

Any of

string

null

submissionUrlstring | null

Show child attributes

Any of

string

null

choicesArray<SurveyService_ChoiceSchema>

Show child attributes

Choice list item (XLSForm choices sheet)

list_namestringrequired

namestringrequired

labelstringrequired

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

media_filestring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionSchema>required

Show child attributes

XLSForm-compatible question schema. Supports all 22 question types with recursive nesting for groups/repeats.

Complete XLSForm-compatible question types (KoboToolbox standard). Reference: https://xlsform.org/en/#question-types

namestringrequired

labelstring

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

hintTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraintMessageTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | null

Show child attributes

Any of

string

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionSchema> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionSchema>

null

calendar_configSurveyService_CalendarConfigSchema | null

Show child attributes

Any of

Configuration for calendar_grid question type

modestringmonthly

months_backinteger[1, 120]12

start_fromstringtoday

allow_futurebooleanfalse

null

calendar_rulesArray<SurveyService_CalendarRuleSchema> | null

Auto-prefill rules for calendar columns

Show child attributes

Any of

Array<SurveyService_CalendarRuleSchema>

Show child attributes

Rule for auto-prefilling calendar column values

idstring | null

Unique rule ID

Show child attributes

Any of

string

null

trigger_questionstringrequired

Question name that triggers this rule

target_columnstringrequired

Calendar column key to fill

value_sourcestringconstant

Where to get the value: constant, lookup, or xpath expression

source_valuestring | null

Constant value to fill (for constant source)

Show child attributes

Any of

string

null

backfill_monthsinteger | null1

How many months to backfill from anchor

Show child attributes

Any of

integer[1, 120]

null

backfill_anchorstring | SurveyService_BackfillAnchorSchema | nullcurrent_month

Anchor for backfill: 'current_month', or anchor config object

Show child attributes

Any of

string

Anchor configuration for timeline-aware backfill

typestringrequired

Anchor type

questionstring | null

Question name (for from_answer_month type)

Show child attributes

Any of

string

null

rule_idstring | null

Rule ID to anchor to (for before_rule/after_rule types)

Show child attributes

Any of

string

null

map_valuesobject | null

Map trigger values to calendar values (e.g., {'yes': 'Y', 'no': 'N'})

Show child attributes

Any of

[key: string]string

null

xpath_expressionstring | null

XPath expression to calculate value (for xpath source)

Show child attributes

Any of

string

null

enabledbooleantrue

Whether rule is active

conditionsArray<object> | null

Conditions for when the rule applies (Visual Rule Builder)

Show child attributes

Any of

Array<object>

null

months_scopeobject | null

Months scope configuration for the rule

Show child attributes

Any of

object

null

columnsArray<SurveyService_CalendarColumnSchema> | null

Show child attributes

Any of

Array<SurveyService_CalendarColumnSchema>

Show child attributes

Column definition for calendar_grid question type

keystringrequired

typestringselect_one

labelstring

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

choicesArray<object> | null

Choices for select_one type - name must be exactly 1 character

Show child attributes

Any of

Array<object>

null

relevantstring | null

Show child attributes

Any of

string

null

limitSurveyService_LimitSchema | null

Show child attributes

Any of

Limit configuration for text/number fields. For text: min/max character count For integer/decimal: min/max value

mininteger | null

Show child attributes

Any of

integer

null

maxinteger | null

Show child attributes

Any of

integer

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

mediaAudiostring | null

Show child attributes

Any of

string

null

mediaAudioSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioUrlstring | null

Show child attributes

Any of

string

null

mediaAudioAssetIdstring | null

Show child attributes

Any of

string

null

mediaAudioUrlSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioAssetIdSchemaobject | null

Show child attributes

Any of

[key: string]string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

lookupsArray<SurveyService_LookupSchema>

Show child attributes

Lookup data item (custom lookups worksheet). Used for cascading selects and external data lookups.

Example:

lookup_name: "countries" or "states"
key: "us" or "ny"
value: "United States" or "New York"
parent_key: None for countries, "us" for states (cascading)
extra_data: {"code": "USA", "region": "north_america"}

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

Example

{
  "settings": {
    "form_title": "string",
    "form_id": "string",
    "version": "string",
    "defaultLanguage": "en",
    "languages": [
      "string"
    ],
    "availableLanguages": [
      "string"
    ],
    "instanceName": "string",
    "submissionUrl": "string"
  },
  "choices": [
    {
      "list_name": "string",
      "name": "string",
      "label": "string",
      "labelTranslations": {},
      "media_file": "string",
      "constraint": "string"
    }
  ],
  "questions": [
    {
      "type": "text",
      "name": "string",
      "label": "",
      "required": false,
      "hint": "string",
      "labelTranslations": {},
      "hintTranslations": {},
      "default": "string",
      "order_index": 0,
      "additional_values": [
        "string"
      ],
      "read_only": false,
      "appearance": "string",
      "relevant": "string",
      "constraint": "string",
      "constraint_message": "string",
      "constraintMessageTranslations": {},
      "calculation": "string",
      "choices": "string",
      "choice_filter": "string",
      "choice_relation": "string",
      "repeat_count": "string",
      "questions": [],
      "calendar_config": {
        "mode": "monthly",
        "months_back": 12,
        "start_from": "today",
        "allow_future": false
      },
      "calendar_rules": [
        {
          "id": "string",
          "trigger_question": "string",
          "target_column": "string",
          "value_source": "constant",
          "source_value": "string",
          "backfill_months": 1,
          "backfill_anchor": "current_month",
          "map_values": {},
          "xpath_expression": "string",
          "enabled": true,
          "conditions": [
            {}
          ],
          "months_scope": {}
        }
      ],
      "columns": [
        {
          "key": "string",
          "type": "select_one",
          "label": "",
          "label_translations": {},
          "choices": [
            {}
          ],
          "relevant": "string"
        }
      ],
      "limit": {
        "min": 0,
        "max": 0
      },
      "paradata": [
        "string"
      ],
      "media_file": "string",
      "mediaAudio": "string",
      "mediaAudioSchema": {},
      "mediaAudioUrl": "string",
      "mediaAudioAssetId": "string",
      "mediaAudioUrlSchema": {},
      "mediaAudioAssetIdSchema": {},
      "deidentify": false,
      "unique_id": false,
      "lookups": "string"
    }
  ],
  "lookups": [
    {
      "lookup_name": "string",
      "key": "string",
      "value": "string",
      "parent_key": "string",
      "extra_data": {}
    }
  ],
  "lookup_data": [
    {}
  ]
}

SurveyService_SurveySchemaResponse

object

Response model for survey schema

settingsobjectrequired

choicesArray<object>

questionsArray<SurveyService_SurveyQuestionResponse>required

Show child attributes

Response model for question (mirrors SurveyQuestionSchema)

typestringrequired

namestringrequired

labelstringrequired

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

hint_translationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraint_message_translationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | Array<object> | null

Show child attributes

Any of

string

Array<object>

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionResponse> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionResponse>

null

limitobject | null

Show child attributes

Any of

object

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

calendar_configobject | null

Show child attributes

Any of

object

null

calendar_rulesArray<object> | null

Show child attributes

Any of

Array<object>

null

columnsArray<object> | null

Show child attributes

Any of

Array<object>

null

lookupsArray<SurveyService_LookupResponse>

Show child attributes

Response model for lookup data

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

Example

{
  "settings": {},
  "choices": [
    {}
  ],
  "questions": [
    {
      "type": "string",
      "name": "string",
      "label": "string",
      "label_translations": {},
      "required": false,
      "hint": "string",
      "hint_translations": {},
      "default": "string",
      "order_index": 0,
      "additional_values": [
        "string"
      ],
      "read_only": false,
      "appearance": "string",
      "relevant": "string",
      "constraint": "string",
      "constraint_message": "string",
      "constraint_message_translations": {},
      "calculation": "string",
      "choices": "string",
      "choice_filter": "string",
      "choice_relation": "string",
      "repeat_count": "string",
      "questions": [],
      "limit": {},
      "paradata": [
        "string"
      ],
      "media_file": "string",
      "deidentify": false,
      "unique_id": false,
      "lookups": "string",
      "calendar_config": {},
      "calendar_rules": [
        {}
      ],
      "columns": [
        {}
      ]
    }
  ],
  "lookups": [
    {
      "lookup_name": "string",
      "key": "string",
      "value": "string",
      "parent_key": "string",
      "extra_data": {}
    }
  ],
  "lookup_data": [
    {}
  ]
}

SurveyService_SurveyStatus

string

SurveyService_SurveyStatusdraftpublishedarchived

SurveyService_SurveyStatusUpdate

object

statusSurveyService_SurveyStatusdraftpublishedarchivedrequired

SurveyService_SurveyTagAssignment

object

tag_idsArray<string>required

SurveyService_SurveyTemplateCreate

object

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanfalse

category_idstringrequired

ID of the template category

tenant_idstring | null

Tenant ID (null for global templates)

Show child attributes

Any of

string

null

SurveyService_SurveyTemplateDetailResponse

object

idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

category_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanrequired

created_bystringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_TemplateCategoryResponserequired

Show child attributes

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

Example

{
  "id": "string",
  "tenant_id": "string",
  "category_id": "string",
  "name": "string",
  "description": "string",
  "schema": {},
  "is_public": true,
  "created_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "icon_name": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
}

SurveyService_SurveyTemplateListResponse

object

itemsArray<SurveyService_SurveyTemplateResponse>required

Show child attributes

idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

category_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanrequired

created_bystringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_TemplateCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

null

totalintegerrequired

limitintegerrequired

skipintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "category_id": "string",
      "name": "string",
      "description": "string",
      "schema": {},
      "is_public": true,
      "created_by": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "category": {
        "id": "string",
        "tenant_id": "string",
        "name": "string",
        "description": "string",
        "icon_name": "string",
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    }
  ],
  "total": 0,
  "limit": 0,
  "skip": 0,
  "has_next": true,
  "has_previous": true
}

SurveyService_SurveyTemplateResponse

object

idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

category_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanrequired

created_bystringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_TemplateCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

null

Example

{
  "id": "string",
  "tenant_id": "string",
  "category_id": "string",
  "name": "string",
  "description": "string",
  "schema": {},
  "is_public": true,
  "created_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "icon_name": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  }
}

SurveyService_SurveyTemplateUpdate

object

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

category_idstring | null

Show child attributes

Any of

string

null

is_publicboolean | null

Show child attributes

Any of

boolean

null

SurveyService_SurveyUpdate

object

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

is_anonymousboolean | null

Show child attributes

Any of

boolean

null

allow_multiple_responsesboolean | null

Show child attributes

Any of

boolean

null

open_atstring | null

Show child attributes

Any of

string<date-time>

null

close_atstring | null

Show child attributes

Any of

string<date-time>

null

scheduling_enabledboolean | null

Show child attributes

Any of

boolean

null

Example

{
  "name": "string",
  "description": "string",
  "is_anonymous": true,
  "allow_multiple_responses": true,
  "open_at": "2024-01-15T09:30:00Z",
  "close_at": "2024-01-15T09:30:00Z",
  "scheduling_enabled": true
}

SurveyService_SurveyVersionCreate

object

DTO for creating a new survey version

survey_idstring | null

Show child attributes

Any of

string<uuid>

null

schemaSurveyService_SurveySchema | null

Show child attributes

Any of

Complete XLSForm-compatible survey schema. Stored in JSONB column in survey_versions table. Includes support for custom lookups worksheet for cascading selects.

settingsSurveyService_SettingsSchemarequired

Survey-level settings (XLSForm settings sheet)

Show child attributes

form_titlestringrequired

form_idstring | null

Show child attributes

Any of

string

null

versionstring | null

Show child attributes

Any of

string

null

defaultLanguagestring | nullen

Show child attributes

Any of

string

null

languagesArray<string> | null

Show child attributes

Any of

Array<string>

null

availableLanguagesArray<string> | null

Show child attributes

Any of

Array<string>

null

instanceNamestring | null

Show child attributes

Any of

string

null

submissionUrlstring | null

Show child attributes

Any of

string

null

choicesArray<SurveyService_ChoiceSchema>

Show child attributes

Choice list item (XLSForm choices sheet)

list_namestringrequired

namestringrequired

labelstringrequired

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

media_filestring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionSchema>required

Show child attributes

XLSForm-compatible question schema. Supports all 22 question types with recursive nesting for groups/repeats.

Complete XLSForm-compatible question types (KoboToolbox standard). Reference: https://xlsform.org/en/#question-types

namestringrequired

labelstring

requiredbooleanfalse

hintstring | null

Show child attributes

Any of

string

null

labelTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

hintTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

defaultstring | null

Show child attributes

Any of

string

null

order_indexinteger0

additional_valuesArray<string> | null

Show child attributes

Any of

Array<string>

null

read_onlybooleanfalse

appearancestring | null

Show child attributes

Any of

string

null

relevantstring | null

Show child attributes

Any of

string

null

constraintstring | null

Show child attributes

Any of

string

null

constraint_messagestring | null

Show child attributes

Any of

string

null

constraintMessageTranslationsobject | null

Show child attributes

Any of

[key: string]string

null

calculationstring | null

Show child attributes

Any of

string

null

choicesstring | null

Show child attributes

Any of

string

null

choice_filterstring | null

Show child attributes

Any of

string

null

choice_relationstring | null

Show child attributes

Any of

string

null

repeat_countstring | null

Show child attributes

Any of

string

null

questionsArray<SurveyService_SurveyQuestionSchema> | null

Show child attributes

Any of

Array<SurveyService_SurveyQuestionSchema>

null

calendar_configSurveyService_CalendarConfigSchema | null

Show child attributes

Any of

Configuration for calendar_grid question type

modestringmonthly

months_backinteger[1, 120]12

start_fromstringtoday

allow_futurebooleanfalse

null

calendar_rulesArray<SurveyService_CalendarRuleSchema> | null

Auto-prefill rules for calendar columns

Show child attributes

Any of

Array<SurveyService_CalendarRuleSchema>

Show child attributes

Rule for auto-prefilling calendar column values

idstring | null

Unique rule ID

Show child attributes

Any of

string

null

trigger_questionstringrequired

Question name that triggers this rule

target_columnstringrequired

Calendar column key to fill

value_sourcestringconstant

Where to get the value: constant, lookup, or xpath expression

source_valuestring | null

Constant value to fill (for constant source)

Show child attributes

Any of

string

null

backfill_monthsinteger | null1

How many months to backfill from anchor

Show child attributes

Any of

integer[1, 120]

null

backfill_anchorstring | SurveyService_BackfillAnchorSchema | nullcurrent_month

Anchor for backfill: 'current_month', or anchor config object

Show child attributes

Any of

string

Anchor configuration for timeline-aware backfill

typestringrequired

Anchor type

questionstring | null

Question name (for from_answer_month type)

Show child attributes

Any of

Max depth reached

rule_idstring | null

Rule ID to anchor to (for before_rule/after_rule types)

Show child attributes

Any of

Max depth reached

null

map_valuesobject | null

Map trigger values to calendar values (e.g., {'yes': 'Y', 'no': 'N'})

Show child attributes

Any of

[key: string]string

null

xpath_expressionstring | null

XPath expression to calculate value (for xpath source)

Show child attributes

Any of

string

null

enabledbooleantrue

Whether rule is active

conditionsArray<object> | null

Conditions for when the rule applies (Visual Rule Builder)

Show child attributes

Any of

Array<object>

null

months_scopeobject | null

Months scope configuration for the rule

Show child attributes

Any of

object

null

columnsArray<SurveyService_CalendarColumnSchema> | null

Show child attributes

Any of

Array<SurveyService_CalendarColumnSchema>

Show child attributes

Column definition for calendar_grid question type

keystringrequired

typestringselect_one

labelstring

label_translationsobject | null

Show child attributes

Any of

[key: string]string

null

choicesArray<object> | null

Choices for select_one type - name must be exactly 1 character

Show child attributes

Any of

Array<object>

null

relevantstring | null

Show child attributes

Any of

string

null

limitSurveyService_LimitSchema | null

Show child attributes

Any of

Limit configuration for text/number fields. For text: min/max character count For integer/decimal: min/max value

mininteger | null

Show child attributes

Any of

integer

null

maxinteger | null

Show child attributes

Any of

integer

null

paradataArray<string> | null

Show child attributes

Any of

Array<string>

null

media_filestring | null

Show child attributes

Any of

string

null

mediaAudiostring | null

Show child attributes

Any of

string

null

mediaAudioSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioUrlstring | null

Show child attributes

Any of

string

null

mediaAudioAssetIdstring | null

Show child attributes

Any of

string

null

mediaAudioUrlSchemaobject | null

Show child attributes

Any of

[key: string]string

null

mediaAudioAssetIdSchemaobject | null

Show child attributes

Any of

[key: string]string

null

deidentifybooleanfalse

unique_idbooleanfalse

lookupsstring | null

Show child attributes

Any of

string

null

lookupsArray<SurveyService_LookupSchema>

Show child attributes

Lookup data item (custom lookups worksheet). Used for cascading selects and external data lookups.

Example:

lookup_name: "countries" or "states"
key: "us" or "ny"
value: "United States" or "New York"
parent_key: None for countries, "us" for states (cascading)
extra_data: {"code": "USA", "region": "north_america"}

lookup_namestringrequired

keystringrequired

valuestringrequired

parent_keystring | null

Show child attributes

Any of

string

null

extra_dataobject | null

Show child attributes

Any of

object

null

lookup_dataArray<object> | null

Show child attributes

Any of

Array<object>

null

versionstring | null

Show child attributes

Any of

string

null

increment_typestring | nullpatch

Show child attributes

Any of

string

null

Example

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "schema": {
    "settings": {
      "form_title": "string",
      "form_id": "string",
      "version": "string",
      "defaultLanguage": "en",
      "languages": [
        "string"
      ],
      "availableLanguages": [
        "string"
      ],
      "instanceName": "string",
      "submissionUrl": "string"
    },
    "choices": [
      {
        "list_name": "string",
        "name": "string",
        "label": "string",
        "labelTranslations": {},
        "media_file": "string",
        "constraint": "string"
      }
    ],
    "questions": [
      {
        "type": "text",
        "name": "string",
        "label": "",
        "required": false,
        "hint": "string",
        "labelTranslations": {},
        "hintTranslations": {},
        "default": "string",
        "order_index": 0,
        "additional_values": [
          "string"
        ],
        "read_only": false,
        "appearance": "string",
        "relevant": "string",
        "constraint": "string",
        "constraint_message": "string",
        "constraintMessageTranslations": {},
        "calculation": "string",
        "choices": "string",
        "choice_filter": "string",
        "choice_relation": "string",
        "repeat_count": "string",
        "questions": [],
        "calendar_config": {
          "mode": "monthly",
          "months_back": 12,
          "start_from": "today",
          "allow_future": false
        },
        "calendar_rules": [
          {
            "id": "string",
            "trigger_question": "string",
            "target_column": "string",
            "value_source": "constant",
            "source_value": "string",
            "backfill_months": 1,
            "backfill_anchor": "current_month",
            "map_values": {},
            "xpath_expression": "string",
            "enabled": true,
            "conditions": [
              {}
            ],
            "months_scope": {}
          }
        ],
        "columns": [
          {
            "key": "string",
            "type": "select_one",
            "label": "",
            "label_translations": {},
            "choices": [
              {}
            ],
            "relevant": "string"
          }
        ],
        "limit": {
          "min": 0,
          "max": 0
        },
        "paradata": [
          "string"
        ],
        "media_file": "string",
        "mediaAudio": "string",
        "mediaAudioSchema": {},
        "mediaAudioUrl": "string",
        "mediaAudioAssetId": "string",
        "mediaAudioUrlSchema": {},
        "mediaAudioAssetIdSchema": {},
        "deidentify": false,
        "unique_id": false,
        "lookups": "string"
      }
    ],
    "lookups": [
      {
        "lookup_name": "string",
        "key": "string",
        "value": "string",
        "parent_key": "string",
        "extra_data": {}
      }
    ],
    "lookup_data": [
      {}
    ]
  },
  "version": "string",
  "increment_type": "patch"
}

SurveyService_SurveyVersionUpdate

object

DTO for updating a draft survey version (cannot update published).

Accepts schema in two formats:

Direct format: { settings, choices, questions, ... }
Wrapped format: { schema: { settings, choices, questions, ... } }

The 'schema' field (when present) may include additional metadata like 'title' and 'version' which are stripped during parsing.

schemaobject | null

Show child attributes

Any of

object

null

settingsany | null

Show child attributes

Any of

any

null

choicesany | null

Show child attributes

Any of

any

null

questionsany | null

Show child attributes

Any of

any

null

lookupsany | null

Show child attributes

Any of

any

null

lookup_dataany | null

Show child attributes

Any of

any

null

SurveyService_SurveyWithAccessResponse

object

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

statusstringrequired

survey_codeinteger | null

Show child attributes

Any of

integer

null

versionstring | null

Show child attributes

Any of

string

null

access_levelstringrequired

can_fillbooleanrequired

can_viewbooleanrequired

can_approvebooleanfalse

created_atstring<date-time>required

updated_atstring | null

Show child attributes

Any of

string<date-time>

null

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "status": "string",
  "survey_code": 0,
  "version": "string",
  "access_level": "string",
  "can_fill": true,
  "can_view": true,
  "can_approve": false,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

SurveyService_TagCreate

object

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

SurveyService_TagListResponse

object

itemsArray<SurveyService_TagResponse>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

totalintegerrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "color": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "total": 0
}

SurveyService_TagResponse

object

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

colorstring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "color": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

SurveyService_TagUpdate

object

namestring | null

Show child attributes

Any of

string

null

colorstring | null

Show child attributes

Any of

string

null

SurveyService_TemplateCategoryCreate

object

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

SurveyService_TemplateCategoryListResponse

object

itemsArray<SurveyService_TemplateCategoryResponse>required

Show child attributes

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

totalintegerrequired

limitintegerrequired

skipintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "tenant_id": "string",
      "name": "string",
      "description": "string",
      "icon_name": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "limit": 0,
  "skip": 0,
  "has_next": true,
  "has_previous": true
}

SurveyService_TemplateCategoryResponse

object

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

Example

{
  "id": "string",
  "tenant_id": "string",
  "name": "string",
  "description": "string",
  "icon_name": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

SurveyService_TemplateCategoryUpdate

object

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

SurveyService_TemplateImportResponse

object

idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

category_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanrequired

created_bystringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_TemplateCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

null

import_warningsArray<object>

Example

{
  "id": "string",
  "tenant_id": "string",
  "category_id": "string",
  "name": "string",
  "description": "string",
  "schema": {},
  "is_public": true,
  "created_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "icon_name": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "import_warnings": [
    {}
  ]
}

SurveyService_TemplatesByCategoryResponse

object

categorySurveyService_TemplateCategoryResponserequired

Show child attributes

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

templatesArray<SurveyService_SurveyTemplateResponse>required

Show child attributes

idstringrequired

tenant_idstring | null

Show child attributes

Any of

string

null

category_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

schemaobject | null

Show child attributes

Any of

object

null

is_publicbooleanrequired

created_bystringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

categorySurveyService_TemplateCategoryResponse | null

Show child attributes

Any of

idstringrequired

tenant_idstringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

icon_namestring | null

Show child attributes

Any of

string

null

created_atstring<date-time>required

updated_atstring<date-time>required

null

template_countintegerrequired

Example

{
  "category": {
    "id": "string",
    "tenant_id": "string",
    "name": "string",
    "description": "string",
    "icon_name": "string",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "templates": [
    {
      "id": "string",
      "tenant_id": "string",
      "category_id": "string",
      "name": "string",
      "description": "string",
      "schema": {},
      "is_public": true,
      "created_by": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "category": {
        "id": "string",
        "tenant_id": "string",
        "name": "string",
        "description": "string",
        "icon_name": "string",
        "created_at": "2024-01-15T09:30:00Z",
        "updated_at": "2024-01-15T09:30:00Z"
      }
    }
  ],
  "template_count": 0
}

SurveyService_ValidateCollectionGrantResponse

object

validbooleanrequired

project_boundbooleanrequired

grant_idstring | null

Show child attributes

Any of

string

null

kindstring | null

Show child attributes

Any of

string

null

survey_version_idstring | null

Show child attributes

Any of

string

null

granted_atstring | null

Show child attributes

Any of

string

null

project_status_at_issuestring | null

Show child attributes

Any of

string

null

late_arrival_flaggedbooleanfalse

Example

{
  "valid": true,
  "project_bound": true,
  "grant_id": "string",
  "kind": "string",
  "survey_version_id": "string",
  "granted_at": "string",
  "project_status_at_issue": "string",
  "late_arrival_flagged": false
}

SurveyService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

DataService_AnalyticsSummaryDTO

object

survey_idstringrequired

total_responsesintegerrequired

unique_respondentsintegerrequired

response_ratenumber | nullrequired

Show child attributes

Any of

number

null

average_completion_time_secondsnumber | nullrequired

Show child attributes

Any of

number

null

questions_analyzedintegerrequired

top_questionsArray<DataService_QuestionStatsDTO>required

Show child attributes

question_idstringrequired

question_typestringrequired

total_answersintegerrequired

unique_respondentsintegerrequired

most_common_valuestring | nullrequired

Show child attributes

Any of

string

null

most_common_countintegerrequired

Example

{
  "survey_id": "string",
  "total_responses": 0,
  "unique_respondents": 0,
  "response_rate": 0,
  "average_completion_time_seconds": 0,
  "questions_analyzed": 0,
  "top_questions": [
    {
      "question_id": "string",
      "question_type": "string",
      "total_answers": 0,
      "unique_respondents": 0,
      "most_common_value": "string",
      "most_common_count": 0
    }
  ]
}

DataService_AnswerDistributionDTO

object

question_idstringrequired

valuestringrequired

countintegerrequired

percentagenumberrequired

DataService_ApprovalActionResponse

object

successbooleanrequired

messagestringrequired

responseDataService_ResponseDTOrequired

Show child attributes

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

Example

{
  "success": true,
  "message": "string",
  "response": {
    "id": "string",
    "survey_id": "string",
    "tenant_id": "string",
    "version_id": "string",
    "idempotency_key": "string",
    "interview_id": "string",
    "respondent_id": "string",
    "rid": "string",
    "uid": "string",
    "status": "string",
    "answers": 0,
    "completed_answers": 0,
    "progress_percentage": 0,
    "started_at": "string",
    "submitted_at": "string",
    "completed_at": "string",
    "duration_seconds": 0,
    "ip_address": "string",
    "user_agent": "string",
    "metadata": {},
    "is_valid": true,
    "submitted_by": "string",
    "enumerator_user_code": "string",
    "enumerator_email": "string",
    "enumerator_name": "string",
    "respondent_name": "string",
    "respondent_user_code": "string",
    "device_id": "string",
    "sync_batch_id": "string",
    "synced_at": "string",
    "approved_by": "string",
    "approved_at": "string",
    "approval_notes": "string",
    "rejected_by": "string",
    "rejected_at": "string",
    "rejection_reason": "string",
    "review_flags": {},
    "response_language": "string",
    "is_reconciled": false,
    "reconciled_at": "string",
    "reconciliation_grant_id": "string",
    "created_at": "string",
    "updated_at": "string"
  }
}

DataService_AttachmentDeleteResponse

object

messagestringrequired

idstringrequired

DataService_AttachmentListDTO

object

attachmentsArray<DataService_AttachmentResponseDTO>required

Show child attributes

idstringrequired

entity_typestringrequired

entity_idstringrequired

filenamestringrequired

original_filenamestringrequired

file_typestring | nullrequired

Show child attributes

Any of

string

null

mime_typestring | nullrequired

Show child attributes

Any of

string

null

file_sizeintegerrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

uploaded_bystring | nullrequired

Show child attributes

Any of

string

null

checksumstring | nullrequired

Show child attributes

Any of

string

null

is_publicbooleanrequired

field_namestring | null

Show child attributes

Any of

string

null

captured_atstring | null

Show child attributes

Any of

string

null

statusstringrequired

created_atstringrequired

download_urlstring | null

Show child attributes

Any of

string

null

totalintegerrequired

pageintegerrequired

limitintegerrequired

Example

{
  "attachments": [
    {
      "id": "string",
      "entity_type": "string",
      "entity_id": "string",
      "filename": "string",
      "original_filename": "string",
      "file_type": "string",
      "mime_type": "string",
      "file_size": 0,
      "description": "string",
      "uploaded_by": "string",
      "checksum": "string",
      "is_public": true,
      "field_name": "string",
      "captured_at": "string",
      "status": "string",
      "created_at": "string",
      "download_url": "string"
    }
  ],
  "total": 0,
  "page": 0,
  "limit": 0
}

DataService_AttachmentRecordDTO

object

entity_typestringrequired

Type of entity (e.g., 'interview', 'response')

entity_idstring<uuid>required

ID of the associated entity

field_namestring | null

Question field name

Show child attributes

Any of

string

null

filenamestringrequired

Stored filename

original_filenamestringrequired

Original filename

file_typestring | null

File category (image, audio, video, document)

Show child attributes

Any of

string

null

mime_typestring | null

MIME type

Show child attributes

Any of

string

null

file_sizeinteger0

File size in bytes

checksumstring | null

SHA-256 checksum

Show child attributes

Any of

string

null

storage_urlstring | null

URL to the uploaded file

Show child attributes

Any of

string

null

captured_atstring | null

Device capture timestamp

Show child attributes

Any of

string

null

descriptionstring | null

Notes/description

Show child attributes

Any of

string

null

Example

{
  "entity_type": "string",
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "field_name": "string",
  "filename": "string",
  "original_filename": "string",
  "file_type": "string",
  "mime_type": "string",
  "file_size": 0,
  "checksum": "string",
  "storage_url": "string",
  "captured_at": "string",
  "description": "string"
}

DataService_AttachmentResponseDTO

object

idstringrequired

entity_typestringrequired

entity_idstringrequired

filenamestringrequired

original_filenamestringrequired

file_typestring | nullrequired

Show child attributes

Any of

string

null

mime_typestring | nullrequired

Show child attributes

Any of

string

null

file_sizeintegerrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

uploaded_bystring | nullrequired

Show child attributes

Any of

string

null

checksumstring | nullrequired

Show child attributes

Any of

string

null

is_publicbooleanrequired

field_namestring | null

Show child attributes

Any of

string

null

captured_atstring | null

Show child attributes

Any of

string

null

statusstringrequired

created_atstringrequired

download_urlstring | null

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "entity_type": "string",
  "entity_id": "string",
  "filename": "string",
  "original_filename": "string",
  "file_type": "string",
  "mime_type": "string",
  "file_size": 0,
  "description": "string",
  "uploaded_by": "string",
  "checksum": "string",
  "is_public": true,
  "field_name": "string",
  "captured_at": "string",
  "status": "string",
  "created_at": "string",
  "download_url": "string"
}

DataService_Body_generate_random_sample_api_v1_data_sampling_generate_post

object

filestringrequired

sample_sizeintegerrequired

output_formatstringcsv

DataService_Body_generate_random_sample_api_v1_sampling_generate_post

object

filestringrequired

sample_sizeintegerrequired

output_formatstringcsv

DataService_Body_upload_attachment_api_v1_attachments__post

object

entity_typestringrequired

Entity type (response, survey, etc.)

entity_idstring<uuid>required

Entity ID

descriptionstring | null

Description

Show child attributes

Any of

string

null

filestringrequired

File to upload

DataService_BulkApproveRequest

object

survey_idstring | null

Show child attributes

Any of

string<uuid>

null

statusArray<DataService_ResponseStatus> | null

Show child attributes

Any of

Array<DataService_ResponseStatus>draftsubmittedcompletedinvalidatedpending_approvalapprovedrejectedterminated

null

start_datestring | null

Show child attributes

Any of

string<date-time>

null

end_datestring | null

Show child attributes

Any of

string<date-time>

null

response_idsArray<string> | null

Show child attributes

Any of

Array<string>

null

dry_runbooleanfalse

notesstring | null

Show child attributes

Any of

string

null

Example

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "notes": "string"
}

DataService_BulkDeleteRequest

object

survey_idstring | null

Show child attributes

Any of

string<uuid>

null

statusArray<DataService_ResponseStatus> | null

Show child attributes

Any of

Array<DataService_ResponseStatus>draftsubmittedcompletedinvalidatedpending_approvalapprovedrejectedterminated

null

start_datestring | null

Show child attributes

Any of

string<date-time>

null

end_datestring | null

Show child attributes

Any of

string<date-time>

null

response_idsArray<string> | null

Show child attributes

Any of

Array<string>

null

dry_runbooleanfalse

Example

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false
}

DataService_BulkInvalidateRequest

object

survey_idstring | null

Show child attributes

Any of

string<uuid>

null

statusArray<DataService_ResponseStatus> | null

Show child attributes

Any of

Array<DataService_ResponseStatus>draftsubmittedcompletedinvalidatedpending_approvalapprovedrejectedterminated

null

start_datestring | null

Show child attributes

Any of

string<date-time>

null

end_datestring | null

Show child attributes

Any of

string<date-time>

null

response_idsArray<string> | null

Show child attributes

Any of

Array<string>

null

dry_runbooleanfalse

reasonstringrequired

Example

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "reason": "string"
}

DataService_BulkOperationResponseDTO

object

success_countinteger0

failure_countinteger0

skipped_countinteger0

errorsArray<object>

dry_runbooleanfalse

DataService_BulkResponseDTO

object

responsesArray<DataService_BulkResponseItemDTO>required

Show child attributes

idempotency_keystringrequired

Unique key for idempotency

survey_idstring<uuid>required

Survey ID

version_idstring | null

Survey version ID

Show child attributes

Any of

string<uuid>

null

respondent_idstring | null

Show child attributes

Any of

string

null

answersobjectrequired

Question ID to answer mapping

metadataobject | null

Additional metadata (clients send this under the 'metadata' key)

Show child attributes

Any of

object

null

submitted_atstring | null

Show child attributes

Any of

string<date-time>

null

Example

{
  "responses": [
    {
      "idempotency_key": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "version_id": "550e8400-e29b-41d4-a716-446655440000",
      "respondent_id": "string",
      "answers": {},
      "metadata": {},
      "submitted_at": "2024-01-15T09:30:00Z"
    }
  ]
}

DataService_BulkResponseItemDTO

object

idempotency_keystringrequired

Unique key for idempotency

survey_idstring<uuid>required

Survey ID

version_idstring | null

Survey version ID

Show child attributes

Any of

string<uuid>

null

respondent_idstring | null

Show child attributes

Any of

string

null

answersobjectrequired

Question ID to answer mapping

metadataobject | null

Additional metadata (clients send this under the 'metadata' key)

Show child attributes

Any of

object

null

submitted_atstring | null

Show child attributes

Any of

string<date-time>

null

Example

{
  "idempotency_key": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "string",
  "answers": {},
  "metadata": {},
  "submitted_at": "2024-01-15T09:30:00Z"
}

DataService_BulkResponseResultDTO

object

totalintegerrequired

successfulintegerrequired

failedintegerrequired

resultsArray<DataService_BulkResponseResultItemDTO>required

Show child attributes

idempotency_keystringrequired

response_idstring | null

Show child attributes

Any of

string

null

statusstringrequired

errorstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

Example

{
  "total": 0,
  "successful": 0,
  "failed": 0,
  "results": [
    {
      "idempotency_key": "string",
      "response_id": "string",
      "status": "string",
      "error": "string",
      "submitted_at": "string"
    }
  ]
}

DataService_BulkResponseResultItemDTO

object

idempotency_keystringrequired

response_idstring | null

Show child attributes

Any of

string

null

statusstringrequired

errorstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

DataService_BulkUpdateStatusRequest

object

survey_idstring | null

Show child attributes

Any of

string<uuid>

null

statusArray<DataService_ResponseStatus> | null

Show child attributes

Any of

Array<DataService_ResponseStatus>draftsubmittedcompletedinvalidatedpending_approvalapprovedrejectedterminated

null

start_datestring | null

Show child attributes

Any of

string<date-time>

null

end_datestring | null

Show child attributes

Any of

string<date-time>

null

response_idsArray<string> | null

Show child attributes

Any of

Array<string>

null

dry_runbooleanfalse

new_statusstringrequired

Example

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": [
    "draft"
  ],
  "start_date": "2024-01-15T09:30:00Z",
  "end_date": "2024-01-15T09:30:00Z",
  "response_ids": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "dry_run": false,
  "new_status": "string"
}

DataService_DashboardMetricsDTO

object

active_formsintegerrequired

active_enumeratorsintegerrequired

submissions_todayintegerrequired

failed_submissionsintegerrequired

latest_submission_timesArray<DataService_SurveyLatestSubmissionDTO>required

Show child attributes

survey_idstringrequired

latest_submitted_atstring | nullrequired

Show child attributes

Any of

string

null

latest_completed_atstring | nullrequired

Show child attributes

Any of

string

null

timezone_contextstringrequired

Example

{
  "active_forms": 0,
  "active_enumerators": 0,
  "submissions_today": 0,
  "failed_submissions": 0,
  "latest_submission_times": [
    {
      "survey_id": "string",
      "latest_submitted_at": "string",
      "latest_completed_at": "string"
    }
  ],
  "timezone_context": "string"
}

DataService_DuplicateGroupDto

object

idstring<uuid>required

Duplicate group ID

primary_response_idstring<uuid>required

Primary response ID

duplicate_response_idstring<uuid>required

Duplicate response ID

survey_idstring<uuid>required

Survey ID

confidence_scorenumberrequired

Confidence score

criteria_breakdownobjectrequired

Breakdown of scores per criterion

Show child attributes

[key: string]number

statusstringrequired

Status of the duplicate group (flagged, merged, discarded, kept_both)

merged_bystring | null

User who performed the merge

Show child attributes

Any of

string<uuid>

null

merged_atstring | null

When the merge was performed

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

When the duplicate was detected

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "primary_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "duplicate_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "confidence_score": 0,
  "criteria_breakdown": {},
  "status": "string",
  "merged_by": "550e8400-e29b-41d4-a716-446655440000",
  "merged_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z"
}

DataService_DuplicateGroupListDto

object

itemsArray<DataService_DuplicateGroupDto>required

List of duplicate groups

Show child attributes

idstring<uuid>required

Duplicate group ID

primary_response_idstring<uuid>required

Primary response ID

duplicate_response_idstring<uuid>required

Duplicate response ID

survey_idstring<uuid>required

Survey ID

confidence_scorenumberrequired

Confidence score

criteria_breakdownobjectrequired

Breakdown of scores per criterion

Show child attributes

[key: string]number

statusstringrequired

Status of the duplicate group (flagged, merged, discarded, kept_both)

merged_bystring | null

User who performed the merge

Show child attributes

Any of

string<uuid>

null

merged_atstring | null

When the merge was performed

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

When the duplicate was detected

totalintegerrequired

Total number of duplicate groups

skipintegerrequired

Number of items skipped

limitintegerrequired

Number of items per page

has_nextbooleanrequired

Whether there are more items

has_previousbooleanrequired

Whether there are previous items

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "primary_response_id": "550e8400-e29b-41d4-a716-446655440000",
      "duplicate_response_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "confidence_score": 0,
      "criteria_breakdown": {},
      "status": "string",
      "merged_by": "550e8400-e29b-41d4-a716-446655440000",
      "merged_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

DataService_EnrichedAnswerDTO

object

question_idstringrequired

question_typestringrequired

valuestring | null

Show child attributes

Any of

string

null

value_jsonany | null

Show child attributes

Any of

any

null

presigned_urlstring | null

Show child attributes

Any of

string

null

DataService_EnumeratorStatsDTO

object

user_idstringrequired

survey_idstringrequired

total_submissionsintegerrequired

total_rejectedintegerrequired

rejection_ratenumberrequired

avg_duration_secondsnumber | null

Show child attributes

Any of

number

null

duration_countinteger0

avg_quality_scorenumber | null

Show child attributes

Any of

number

null

last_submission_atstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

Example

{
  "user_id": "string",
  "survey_id": "string",
  "total_submissions": 0,
  "total_rejected": 0,
  "rejection_rate": 0,
  "avg_duration_seconds": 0,
  "duration_count": 0,
  "avg_quality_score": 0,
  "last_submission_at": "string",
  "enumerator_name": "string",
  "enumerator_user_code": "string",
  "enumerator_email": "string"
}

DataService_EnumeratorStatsListDTO

object

itemsArray<DataService_EnumeratorStatsDTO>required

Show child attributes

user_idstringrequired

survey_idstringrequired

total_submissionsintegerrequired

total_rejectedintegerrequired

rejection_ratenumberrequired

avg_duration_secondsnumber | null

Show child attributes

Any of

number

null

duration_countinteger0

avg_quality_scorenumber | null

Show child attributes

Any of

number

null

last_submission_atstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

Example

{
  "items": [
    {
      "user_id": "string",
      "survey_id": "string",
      "total_submissions": 0,
      "total_rejected": 0,
      "rejection_rate": 0,
      "avg_duration_seconds": 0,
      "duration_count": 0,
      "avg_quality_score": 0,
      "last_submission_at": "string",
      "enumerator_name": "string",
      "enumerator_user_code": "string",
      "enumerator_email": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0
}

DataService_ExportRequestDTO

object

survey_idstring<uuid>required

Survey ID to export

formatstringcsv

Export format: csv, xlsx, json, dta, sav

statusstring | null

Filter by response status

Show child attributes

Any of

string

null

from_datestring | null

Filter from date

Show child attributes

Any of

string<date-time>

null

to_datestring | null

Filter to date

Show child attributes

Any of

string<date-time>

null

respondent_idstring | null

Filter by respondent

Show child attributes

Any of

string

null

include_metadatabooleantrue

Include response metadata

include_answersbooleantrue

Include answer data

version_idstring | null

Survey version ID for schema labels (uses latest if not set)

Show child attributes

Any of

string

null

languagestring | null

Language code for translated labels (e.g., 'es', 'fr')

Show child attributes

Any of

string

null

Example

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "format": "csv",
  "status": "string",
  "from_date": "2024-01-15T09:30:00Z",
  "to_date": "2024-01-15T09:30:00Z",
  "respondent_id": "string",
  "include_metadata": true,
  "include_answers": true,
  "version_id": "string",
  "language": "string"
}

DataService_HTTPValidationError

object

detailArray<DataService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

DataService_MediaExportStatusDTO

object

request_idstringrequired

task_statusstringrequired

resultobject | null

Show child attributes

Any of

object

null

errorstring | null

Show child attributes

Any of

string

null

DataService_MergeRequestDto

object

target_response_idstring<uuid>required

Response ID to merge into (primary)

merge_notestring | null

Note about the merge

Show child attributes

Any of

string

null

conflict_resolutionsobject | null

Resolutions for conflicting fields (field name -> response ID to keep)

Show child attributes

Any of

[key: string]string

null

DataService_MergeResponseDto

object

successbooleanrequired

Whether the merge was successful

primary_response_idstring<uuid>required

Primary response ID after merge

merged_response_idstring<uuid>required

Response ID that was merged

messagestringrequired

Status message

DataService_PendingApprovalCountDTO

object

survey_idstring<uuid>required

countintegerrequired

DataService_QuestionStatsDTO

object

question_idstringrequired

question_typestringrequired

total_answersintegerrequired

unique_respondentsintegerrequired

most_common_valuestring | nullrequired

Show child attributes

Any of

string

null

most_common_countintegerrequired

DataService_ResponseApprovalRequest

object

notesstring | null

Optional approval notes

Show child attributes

Any of

string

null

DataService_ResponseChangeDTO

object

A single response change. Deliberately carries no answer values.

response_idstringrequired

survey_idstring | null

Show child attributes

Any of

string

null

change_typestringrequired

changed_fieldsArray<string> | null

Show child attributes

Any of

Array<string>

null

changed_atstringrequired

DataService_ResponseChangeFeedDTO

object

itemsArray<DataService_ResponseChangeDTO>required

Show child attributes

A single response change. Deliberately carries no answer values.

response_idstringrequired

survey_idstring | null

Show child attributes

Any of

string

null

change_typestringrequired

changed_fieldsArray<string> | null

Show child attributes

Any of

Array<string>

null

changed_atstringrequired

next_watermarkstringrequired

has_morebooleanrequired

Example

{
  "items": [
    {
      "response_id": "string",
      "survey_id": "string",
      "change_type": "string",
      "changed_fields": [
        "string"
      ],
      "changed_at": "string"
    }
  ],
  "next_watermark": "string",
  "has_more": true
}

DataService_ResponseCorrectionRequest

object

Enumerator correction of a rejected response.

answers must contain only questions the supervisor flagged as checked. Supplying answers for unflagged questions is rejected with 422. Questions omitted here are left unchanged.

answersobjectrequired

Corrected answers for flagged questions only

reasonstring | null

Reason for correction

Show child attributes

Any of

string

null

DataService_ResponseCorrectionResponse

object

successbooleantrue

replayedbooleanfalse

response_idstring<uuid>required

statusstringrequired

edit_idstring | null

Show child attributes

Any of

string<uuid>

null

edit_countintegerrequired

changed_questionsArray<string>required

updated_atstring | null

Show child attributes

Any of

string<date-time>

null

Example

{
  "success": true,
  "replayed": false,
  "response_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "string",
  "edit_id": "550e8400-e29b-41d4-a716-446655440000",
  "edit_count": 0,
  "changed_questions": [
    "string"
  ],
  "updated_at": "2024-01-15T09:30:00Z"
}

DataService_ResponseDTO

object

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

Example

{
  "id": "string",
  "survey_id": "string",
  "tenant_id": "string",
  "version_id": "string",
  "idempotency_key": "string",
  "interview_id": "string",
  "respondent_id": "string",
  "rid": "string",
  "uid": "string",
  "status": "string",
  "answers": 0,
  "completed_answers": 0,
  "progress_percentage": 0,
  "started_at": "string",
  "submitted_at": "string",
  "completed_at": "string",
  "duration_seconds": 0,
  "ip_address": "string",
  "user_agent": "string",
  "metadata": {},
  "is_valid": true,
  "submitted_by": "string",
  "enumerator_user_code": "string",
  "enumerator_email": "string",
  "enumerator_name": "string",
  "respondent_name": "string",
  "respondent_user_code": "string",
  "device_id": "string",
  "sync_batch_id": "string",
  "synced_at": "string",
  "approved_by": "string",
  "approved_at": "string",
  "approval_notes": "string",
  "rejected_by": "string",
  "rejected_at": "string",
  "rejection_reason": "string",
  "review_flags": {},
  "response_language": "string",
  "is_reconciled": false,
  "reconciled_at": "string",
  "reconciliation_grant_id": "string",
  "created_at": "string",
  "updated_at": "string"
}

DataService_ResponseDetailDTO

object

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

answers_listArray<DataService_EnrichedAnswerDTO>

Show child attributes

question_idstringrequired

question_typestringrequired

valuestring | null

Show child attributes

Any of

string

null

value_jsonany | null

Show child attributes

Any of

any

null

presigned_urlstring | null

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "survey_id": "string",
  "tenant_id": "string",
  "version_id": "string",
  "idempotency_key": "string",
  "interview_id": "string",
  "respondent_id": "string",
  "rid": "string",
  "uid": "string",
  "status": "string",
  "answers": 0,
  "completed_answers": 0,
  "progress_percentage": 0,
  "started_at": "string",
  "submitted_at": "string",
  "completed_at": "string",
  "duration_seconds": 0,
  "ip_address": "string",
  "user_agent": "string",
  "metadata": {},
  "is_valid": true,
  "submitted_by": "string",
  "enumerator_user_code": "string",
  "enumerator_email": "string",
  "enumerator_name": "string",
  "respondent_name": "string",
  "respondent_user_code": "string",
  "device_id": "string",
  "sync_batch_id": "string",
  "synced_at": "string",
  "approved_by": "string",
  "approved_at": "string",
  "approval_notes": "string",
  "rejected_by": "string",
  "rejected_at": "string",
  "rejection_reason": "string",
  "review_flags": {},
  "response_language": "string",
  "is_reconciled": false,
  "reconciled_at": "string",
  "reconciliation_grant_id": "string",
  "created_at": "string",
  "updated_at": "string",
  "answers_list": []
}

DataService_ResponseEditHistoryDTO

object

idstring<uuid>required

edited_atstring<date-time>required

edited_bystring<uuid>required

reasonstring | null

Show child attributes

Any of

string

null

changes_countintegerrequired

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "edited_at": "2024-01-15T09:30:00Z",
  "edited_by": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "string",
  "changes_count": 0
}

DataService_ResponseEditHistoryListDTO

object

itemsArray<DataService_ResponseEditHistoryDTO>required

Show child attributes

idstring<uuid>required

edited_atstring<date-time>required

edited_bystring<uuid>required

reasonstring | null

Show child attributes

Any of

string

null

changes_countintegerrequired

totalintegerrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "edited_at": "2024-01-15T09:30:00Z",
      "edited_by": "550e8400-e29b-41d4-a716-446655440000",
      "reason": "string",
      "changes_count": 0
    }
  ],
  "total": 0
}

DataService_ResponseEditRequest

object

answersobjectrequired

Question ID to answer mapping

reasonstring | null

Reason for edit

Show child attributes

Any of

string

null

DataService_ResponseEditResponse

object

successbooleanrequired

edit_idstring<uuid>required

responseDataService_ResponseDetailDTOrequired

Show child attributes

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

answers_listArray<DataService_EnrichedAnswerDTO>

Show child attributes

question_idstringrequired

question_typestringrequired

valuestring | null

Show child attributes

Any of

string

null

value_jsonany | null

Show child attributes

Any of

any

null

presigned_urlstring | null

Show child attributes

Any of

string

null

changes_countintegerrequired

Example

{
  "success": true,
  "edit_id": "550e8400-e29b-41d4-a716-446655440000",
  "response": {
    "id": "string",
    "survey_id": "string",
    "tenant_id": "string",
    "version_id": "string",
    "idempotency_key": "string",
    "interview_id": "string",
    "respondent_id": "string",
    "rid": "string",
    "uid": "string",
    "status": "string",
    "answers": 0,
    "completed_answers": 0,
    "progress_percentage": 0,
    "started_at": "string",
    "submitted_at": "string",
    "completed_at": "string",
    "duration_seconds": 0,
    "ip_address": "string",
    "user_agent": "string",
    "metadata": {},
    "is_valid": true,
    "submitted_by": "string",
    "enumerator_user_code": "string",
    "enumerator_email": "string",
    "enumerator_name": "string",
    "respondent_name": "string",
    "respondent_user_code": "string",
    "device_id": "string",
    "sync_batch_id": "string",
    "synced_at": "string",
    "approved_by": "string",
    "approved_at": "string",
    "approval_notes": "string",
    "rejected_by": "string",
    "rejected_at": "string",
    "rejection_reason": "string",
    "review_flags": {},
    "response_language": "string",
    "is_reconciled": false,
    "reconciled_at": "string",
    "reconciliation_grant_id": "string",
    "created_at": "string",
    "updated_at": "string",
    "answers_list": []
  },
  "changes_count": 0
}

DataService_ResponseListDTO

object

itemsArray<DataService_ResponseDTO>required

Show child attributes

idstringrequired

survey_idstringrequired

tenant_idstringrequired

version_idstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

interview_idstring | null

Show child attributes

Any of

string

null

respondent_idstring | null

Show child attributes

Any of

string

null

ridstring | null

Show child attributes

Any of

string

null

uidstring | null

Show child attributes

Any of

string

null

statusstringrequired

answersintegerrequired

completed_answersintegerrequired

progress_percentageintegerrequired

started_atstring | null

Show child attributes

Any of

string

null

submitted_atstring | null

Show child attributes

Any of

string

null

completed_atstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

is_validbooleanrequired

submitted_bystring | null

Show child attributes

Any of

string

null

enumerator_user_codestring | null

Show child attributes

Any of

string

null

enumerator_emailstring | null

Show child attributes

Any of

string

null

enumerator_namestring | null

Show child attributes

Any of

string

null

respondent_namestring | null

Show child attributes

Any of

string

null

respondent_user_codestring | null

Show child attributes

Any of

string

null

device_idstring | null

Show child attributes

Any of

string

null

sync_batch_idstring | null

Show child attributes

Any of

string

null

synced_atstring | null

Show child attributes

Any of

string

null

approved_bystring | null

Show child attributes

Any of

string

null

approved_atstring | null

Show child attributes

Any of

string

null

approval_notesstring | null

Show child attributes

Any of

string

null

rejected_bystring | null

Show child attributes

Any of

string

null

rejected_atstring | null

Show child attributes

Any of

string

null

rejection_reasonstring | null

Show child attributes

Any of

string

null

review_flagsobject | null

Show child attributes

Any of

object

null

response_languagestring | null

Show child attributes

Any of

string

null

is_reconciledbooleanfalse

reconciled_atstring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "survey_id": "string",
      "tenant_id": "string",
      "version_id": "string",
      "idempotency_key": "string",
      "interview_id": "string",
      "respondent_id": "string",
      "rid": "string",
      "uid": "string",
      "status": "string",
      "answers": 0,
      "completed_answers": 0,
      "progress_percentage": 0,
      "started_at": "string",
      "submitted_at": "string",
      "completed_at": "string",
      "duration_seconds": 0,
      "ip_address": "string",
      "user_agent": "string",
      "metadata": {},
      "is_valid": true,
      "submitted_by": "string",
      "enumerator_user_code": "string",
      "enumerator_email": "string",
      "enumerator_name": "string",
      "respondent_name": "string",
      "respondent_user_code": "string",
      "device_id": "string",
      "sync_batch_id": "string",
      "synced_at": "string",
      "approved_by": "string",
      "approved_at": "string",
      "approval_notes": "string",
      "rejected_by": "string",
      "rejected_at": "string",
      "rejection_reason": "string",
      "review_flags": {},
      "response_language": "string",
      "is_reconciled": false,
      "reconciled_at": "string",
      "reconciliation_grant_id": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

DataService_ResponseRejectionRequest

object

reasonstringrequired

Required rejection reason

flagsobjectrequired

Required review flags to persist atomically with the rejection. At least one flag must have checked=true. There is no fallback to previously stored flags.

Show child attributes

[key: string]DataService_ReviewFlag

Show child attributes

checkedbooleanfalse

notestring | null

Show child attributes

Any of

string

null

DataService_ResponseStatsDTO

object

survey_idstringrequired

total_responsesintegerrequired

draft_countintegerrequired

submitted_countintegerrequired

completed_countintegerrequired

invalidated_countintegerrequired

completion_ratenumberrequired

average_duration_secondsnumber | nullrequired

Show child attributes

Any of

number

null

date_fromstringrequired

date_tostringrequired

Example

{
  "survey_id": "string",
  "total_responses": 0,
  "draft_count": 0,
  "submitted_count": 0,
  "completed_count": 0,
  "invalidated_count": 0,
  "completion_rate": 0,
  "average_duration_seconds": 0,
  "date_from": "string",
  "date_to": "string"
}

DataService_ResponseStatus

string

DataService_ResponseStatusdraftsubmittedcompletedinvalidatedpending_approvalapprovedrejectedterminated

DataService_ResponseValidationErrorDTO

object

errorstringrequired

validation_errorsArray<object>required

DataService_ReviewFlag

object

checkedbooleanfalse

notestring | null

Show child attributes

Any of

string

null

DataService_SimilarityMatch

object

response_idstring<uuid>required

ID of the potentially duplicate response

confidencenumberrequired

Confidence score (0-1)

criteria_breakdownobjectrequired

Breakdown of scores per criterion

Show child attributes

[key: string]number

response_detailsobject | null

Additional details about the matched response

Show child attributes

Any of

object

null

DataService_SimilaritySearchRequest

object

survey_idstringrequired

Survey ID to search for duplicates in

respondent_idstring | null

Respondent ID to match

Show child attributes

Any of

string

null

respondent_fieldsobject | null

Other respondent fields for matching

Show child attributes

Any of

object

null

gps_coordinatesobject | null

GPS coordinates for proximity match

Show child attributes

Any of

[key: string]number

null

DataService_SimilaritySearchResponse

object

matchesArray<DataService_SimilarityMatch>required

List of potential duplicates

Show child attributes

response_idstring<uuid>required

ID of the potentially duplicate response

confidencenumberrequired

Confidence score (0-1)

criteria_breakdownobjectrequired

Breakdown of scores per criterion

Show child attributes

[key: string]number

response_detailsobject | null

Additional details about the matched response

Show child attributes

Any of

object

null

totalintegerrequired

Total number of matches found

Example

{
  "matches": [
    {
      "response_id": "550e8400-e29b-41d4-a716-446655440000",
      "confidence": 0,
      "criteria_breakdown": {},
      "response_details": {}
    }
  ],
  "total": 0
}

DataService_SubmitResponseDTO

object

survey_idstring<uuid>required

Survey ID

version_idstring | null

Survey version ID

Show child attributes

Any of

string<uuid>

null

idempotency_keystring | null

Unique key for submission idempotency

Show child attributes

Any of

string

null

respondent_idstring | null

Respondent identifier

Show child attributes

Any of

string

null

answersobjectrequired

Question ID to answer mapping

metadataobject | null

Additional metadata (clients send this under the 'metadata' key)

Show child attributes

Any of

object

null

ip_addressstring | null

Client IP address

Show child attributes

Any of

string

null

user_agentstring | null

Client user agent

Show child attributes

Any of

string

null

device_idstring | null

Device identifier (ODK Collect deviceID, CSPro device ID)

Show child attributes

Any of

string

null

sync_batch_idstring | null

Batch ID for grouping offline sync submissions

Show child attributes

Any of

string<uuid>

null

submission_modestring | nullcomplete

Domain-level intent: 'complete' or 'terminated_partial'

Show child attributes

Any of

string

null

duration_secondsinteger | null

Active form filling duration in seconds, excluding paused time

Show child attributes

Any of

integer[0, 2592000]

null

interview_idstring | null

Interview execution ID — links this response to its interview lifecycle

Show child attributes

Any of

string<uuid>

null

interview_ridstring | null

Response RID from interview (generated at interview creation, not at submission)

Show child attributes

Any of

string

null

collected_atstring | null

Show child attributes

Any of

string<date-time>

null

response_languagestring | null

Language code used for this submission (e.g., 'en', 'es', 'fr')

Show child attributes

Any of

string

null

is_reconciliationbooleanfalse

Flag indicating this submission is a server-authorized reconciliation of work predating revocation (R22)

reconciliation_grant_idstring | null

Historical form access grant ID authorizing this reconciliation

Show child attributes

Any of

string<uuid>

null

Example

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "idempotency_key": "string",
  "respondent_id": "string",
  "answers": {},
  "metadata": {},
  "ip_address": "string",
  "user_agent": "string",
  "device_id": "string",
  "sync_batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "submission_mode": "complete",
  "duration_seconds": 0,
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "response_language": "string",
  "is_reconciliation": false,
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000"
}

DataService_SurveyLatestSubmissionDTO

object

survey_idstringrequired

latest_submitted_atstring | nullrequired

Show child attributes

Any of

string

null

latest_completed_atstring | nullrequired

Show child attributes

Any of

string

null

DataService_TimeSeriesDTO

object

survey_idstringrequired

granularitystringrequired

dataArray<DataService_TimeSeriesPointDTO>required

Show child attributes

datestringrequired

countintegerrequired

DataService_TimeSeriesPointDTO

object

datestringrequired

countintegerrequired

DataService_UpdateAttachmentDTO

object

descriptionstring | null

Updated notes/description

Show child attributes

Any of

string

null

field_namestring | null

Updated question field name

Show child attributes

Any of

string

null

DataService_UpdateResponseDTO

object

respondent_idstring | null

Show child attributes

Any of

string

null

metadataobject | null

Additional metadata (clients send this under the 'metadata' key)

Show child attributes

Any of

object

null

statusstring | null

Show child attributes

Any of

string

null

DataService_UpdateReviewFlagsRequest

object

flagsobject

Question ID to review flag mapping

Show child attributes

[key: string]DataService_ReviewFlag

Show child attributes

checkedbooleanfalse

notestring | null

Show child attributes

Any of

string

null

DataService_ValidateIdsRequest

object

response_idsArray<string>required

DataService_ValidateIdsResponse

object

valid_idsArray<string>required

DataService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

SyncService_BulkSyncPushRequestDTO

object

Bulk push sync request.

responsesArray<SyncService_SyncPushRequestDTO>required

Max 50 responses per batch

Show child attributes

Push sync request for single response.

idempotency_keystringrequired

Unique key for idempotency

survey_idstring<uuid>required

Survey ID

survey_version_idstring | null

Survey version ID for version-pinned response

Show child attributes

Any of

string<uuid>

null

interview_idstring | null

Interview execution ID — links this response to its interview lifecycle (Track A)

Show child attributes

Any of

string<uuid>

null

interview_ridstring | null

Response RID allocated for interview

Show child attributes

Any of

string

null

respondent_idstring | null

Respondent identifier

Show child attributes

Any of

string

null

answersArray<SyncService_ResponseAnswerDTO>required

Survey answers

Show child attributes

Response answer data.

question_idstringrequired

valueany

metadataobject | null

Additional metadata

Show child attributes

Any of

object

null

device_idstringrequired

Device that collected the response

collected_atstring | null

When response was collected on device

Show child attributes

Any of

string<date-time>

null

response_languagestring | null

Language code used for submission (e.g., 'en', 'es')

Show child attributes

Any of

string

null

submission_modestring | null

Submission mode: 'complete', 'terminated_partial', or 'draft'

Show child attributes

Any of

string

null

Example

{
  "responses": [
    {
      "idempotency_key": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_rid": "string",
      "respondent_id": "string",
      "answers": [
        {
          "question_id": "string"
        }
      ],
      "metadata": {},
      "device_id": "string",
      "collected_at": "2024-01-15T09:30:00Z",
      "response_language": "string",
      "submission_mode": "string"
    }
  ]
}

SyncService_BulkSyncPushResponseDTO

object

Bulk push sync response.

totalintegerrequired

acceptedintegerrequired

rejectedintegerrequired

resultsArray<SyncService_SyncPushResponseDTO>required

Show child attributes

Push sync response.

idstringrequired

idempotency_keystringrequired

statusstringrequired

response_idstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

lifecycle_codestring | null

Show child attributes

Any of

string

null

Example

{
  "total": 0,
  "accepted": 0,
  "rejected": 0,
  "results": [
    {
      "id": "string",
      "idempotency_key": "string",
      "status": "string",
      "response_id": "string",
      "created_at": "string",
      "lifecycle_code": "string"
    }
  ]
}

SyncService_ConflictDTO

object

Sync conflict information.

idstring<uuid>required

tenant_idstring<uuid>required

device_idstringrequired

response_idstringrequired

conflict_typestringrequired

server_versionobject | null

Show child attributes

Any of

object

null

client_versionobject | null

Show child attributes

Any of

object

null

resolutionstring | null

Show child attributes

Any of

string

null

resolved_atstring | null

Show child attributes

Any of

string<date-time>

null

resolved_bystring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "response_id": "string",
  "conflict_type": "string",
  "server_version": {},
  "client_version": {},
  "resolution": "string",
  "resolved_at": "2024-01-15T09:30:00Z",
  "resolved_by": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z"
}

SyncService_ConflictListDTO

object

List of sync conflicts.

itemsArray<SyncService_ConflictDTO>required

Show child attributes

Sync conflict information.

idstring<uuid>required

tenant_idstring<uuid>required

device_idstringrequired

response_idstringrequired

conflict_typestringrequired

server_versionobject | null

Show child attributes

Any of

object

null

client_versionobject | null

Show child attributes

Any of

object

null

resolutionstring | null

Show child attributes

Any of

string

null

resolved_atstring | null

Show child attributes

Any of

string<date-time>

null

resolved_bystring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

totalintegerrequired

skipinteger0

limitinteger100

has_nextbooleanfalse

has_previousbooleanfalse

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "device_id": "string",
      "response_id": "string",
      "conflict_type": "string",
      "server_version": {},
      "client_version": {},
      "resolution": "string",
      "resolved_at": "2024-01-15T09:30:00Z",
      "resolved_by": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 100,
  "has_next": false,
  "has_previous": false
}

SyncService_ConflictResolutionRequestDTO

object

Request to resolve a sync conflict.

strategystringrequired

Resolution strategy: server_wins, client_wins, or manual

merged_dataobject | null

Merged data if manual strategy is used

Show child attributes

Any of

object

null

SyncService_DeviceListDTO

object

List of devices response.

itemsArray<SyncService_DeviceResponseDTO>required

Show child attributes

Device response.

idstringrequired

device_idstringrequired

platformstringrequired

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_primarybooleanrequired

last_active_atstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipinteger0

limitinteger100

has_nextbooleanfalse

has_previousbooleanfalse

Example

{
  "items": [
    {
      "id": "string",
      "device_id": "string",
      "platform": "string",
      "device_name": "string",
      "device_model": "string",
      "os_version": "string",
      "app_version": "string",
      "status": "string",
      "is_primary": true,
      "last_active_at": "string",
      "created_at": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 100,
  "has_next": false,
  "has_previous": false
}

SyncService_DeviceRegistrationDTO

object

Device registration request.

device_idstringrequired

Unique device identifier

platformstringrequired

Device platform (ios, android, web, desktop)

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

push_tokenstring | null

Show child attributes

Any of

string

null

Example

{
  "device_id": "string",
  "platform": "string",
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "push_token": "string"
}

SyncService_DeviceResponseDTO

object

Device response.

idstringrequired

device_idstringrequired

platformstringrequired

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

statusstringrequired

is_primarybooleanrequired

last_active_atstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "device_id": "string",
  "platform": "string",
  "device_name": "string",
  "device_model": "string",
  "os_version": "string",
  "app_version": "string",
  "status": "string",
  "is_primary": true,
  "last_active_at": "string",
  "created_at": "string"
}

SyncService_DeviceUpdateDTO

object

Device update request.

device_namestring | null

Show child attributes

Any of

string

null

device_modelstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

push_tokenstring | null

Show child attributes

Any of

string

null

SyncService_FailedSubmissionsDTO

object

countintegerrequired

SyncService_FormDownloadAcknowledgementDTO

object

Client acknowledgement emitted only after a schema is persisted locally.

survey_idstring<uuid>required

survey_version_idstring<uuid>required

survey_versionstringrequired

survey_titlestring | null

Show child attributes

Any of

string

null

schema_hashstring | null

Show child attributes

Any of

string

null

device_idstringrequired

download_idstring<uuid>required

platformstring | null

Show child attributes

Any of

string

null

app_versionstring | null

Show child attributes

Any of

string

null

app_buildstring | null

Show child attributes

Any of

string

null

os_versionstring | null

Show child attributes

Any of

string

null

persisted_atstring | null

Show child attributes

Any of

string<date-time>

null

Example

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version": "string",
  "survey_title": "string",
  "schema_hash": "string",
  "device_id": "string",
  "download_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "string",
  "app_version": "string",
  "app_build": "string",
  "os_version": "string",
  "persisted_at": "2024-01-15T09:30:00Z"
}

SyncService_HTTPValidationError

object

detailArray<SyncService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

SyncService_HealthResponseDTO

object

statusstringrequired

servicestringrequired

versionstringrequired

timestampstring<date-time>required

databasestring | null

Show child attributes

Any of

string

null

SyncService_InitialSyncRequestDTO

object

Initial sync request.

device_idstringrequired

platformstring | nullunknown

Device platform

Show child attributes

Any of

string

null

SyncService_PushTokenUpdateDTO

object

Push token update request.

push_tokenstringrequired

SyncService_ResponseAnswerDTO

object

Response answer data.

question_idstringrequired

valueany

SyncService_RoleSyncDTO

object

Role and permissions descriptor for sync pull response.

idstringrequired

namestringrequired

permissionsArray<string>

SyncService_SurveySyncDTO

object

Survey sync data — a descriptor, not a content channel (D-11).

survey_idstringrequired

version_idstringrequired

versionstringrequired

titlestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

schema_hashstring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

has_lookupsbooleanfalse

questionsArray<object>

settingsobject | null

Show child attributes

Any of

object

null

Example

{
  "survey_id": "string",
  "version_id": "string",
  "version": "string",
  "title": "string",
  "description": "string",
  "status": "string",
  "schema_hash": "string",
  "is_deleted": false,
  "has_lookups": false,
  "questions": [
    {}
  ],
  "settings": {}
}

SyncService_SyncMetadataDTO

object

Sync metadata response.

surveys_modifiedintegerrequired

surveys_deletedintegerrequired

responses_modifiedintegerrequired

responses_newintegerrequired

server_timestampstringrequired

next_sync_tokenstringrequired

SyncService_SyncPullRequestDTO

object

Pull sync request.

device_idstringrequired

Device identifier

last_sync_tokenstring | null

Token from previous sync

Show child attributes

Any of

string

null

survey_versionstring | null

Last known survey version (semver string)

Show child attributes

Any of

string

null

include_surveysbooleantrue

Include survey data

include_metadatabooleantrue

Include sync metadata

SyncService_SyncPullResponseDTO

object

Pull sync response.

sync_tokenstringrequired

surveysArray<SyncService_SurveySyncDTO>required

Show child attributes

Survey sync data — a descriptor, not a content channel (D-11).

survey_idstringrequired

version_idstringrequired

versionstringrequired

titlestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

statusstringrequired

schema_hashstring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

has_lookupsbooleanfalse

questionsArray<object>

settingsobject | null

Show child attributes

Any of

object

null

metadataSyncService_SyncMetadataDTOrequired

Sync metadata response.

Show child attributes

surveys_modifiedintegerrequired

surveys_deletedintegerrequired

responses_modifiedintegerrequired

responses_newintegerrequired

server_timestampstringrequired

next_sync_tokenstringrequired

server_timestampstringrequired

roleSyncService_RoleSyncDTO | null

Show child attributes

Any of

Role and permissions descriptor for sync pull response.

idstringrequired

namestringrequired

permissionsArray<string>

null

Example

{
  "sync_token": "string",
  "surveys": [
    {
      "survey_id": "string",
      "version_id": "string",
      "version": "string",
      "title": "string",
      "description": "string",
      "status": "string",
      "schema_hash": "string",
      "is_deleted": false,
      "has_lookups": false,
      "questions": [
        {}
      ],
      "settings": {}
    }
  ],
  "metadata": {
    "surveys_modified": 0,
    "surveys_deleted": 0,
    "responses_modified": 0,
    "responses_new": 0,
    "server_timestamp": "string",
    "next_sync_token": "string"
  },
  "server_timestamp": "string",
  "role": {
    "id": "string",
    "name": "string",
    "permissions": [
      "string"
    ]
  }
}

SyncService_SyncPushRequestDTO

object

Push sync request for single response.

idempotency_keystringrequired

Unique key for idempotency

survey_idstring<uuid>required

Survey ID

survey_version_idstring | null

Survey version ID for version-pinned response

Show child attributes

Any of

string<uuid>

null

interview_idstring | null

Interview execution ID — links this response to its interview lifecycle (Track A)

Show child attributes

Any of

string<uuid>

null

interview_ridstring | null

Response RID allocated for interview

Show child attributes

Any of

string

null

respondent_idstring | null

Respondent identifier

Show child attributes

Any of

string

null

answersArray<SyncService_ResponseAnswerDTO>required

Survey answers

Show child attributes

Response answer data.

question_idstringrequired

valueany

metadataobject | null

Additional metadata

Show child attributes

Any of

object

null

device_idstringrequired

Device that collected the response

collected_atstring | null

When response was collected on device

Show child attributes

Any of

string<date-time>

null

response_languagestring | null

Language code used for submission (e.g., 'en', 'es')

Show child attributes

Any of

string

null

submission_modestring | null

Submission mode: 'complete', 'terminated_partial', or 'draft'

Show child attributes

Any of

string

null

Example

{
  "idempotency_key": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "respondent_id": "string",
  "answers": [
    {
      "question_id": "string"
    }
  ],
  "metadata": {},
  "device_id": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "response_language": "string",
  "submission_mode": "string"
}

SyncService_SyncPushResponseDTO

object

Push sync response.

idstringrequired

idempotency_keystringrequired

statusstringrequired

response_idstring | null

Show child attributes

Any of

string

null

created_atstring | null

Show child attributes

Any of

string

null

lifecycle_codestring | null

Show child attributes

Any of

string

null

SyncService_SyncReconciliationRequestDTO

object

Server-authorized reconciliation request for responses predating access revocation (R17 & R22).

intentstringrequired

Explicit intent: must be 'reconcile_revoked_work'

idempotency_keystringrequired

Unique key for idempotency

survey_idstring<uuid>required

Survey ID

survey_version_idstring | null

Survey version ID for version pinning

Show child attributes

Any of

string<uuid>

null

device_idstringrequired

Device that collected the response

collected_atstring<date-time>required

Device-reported capture timestamp (mandatory for reconciliation)

answersArray<SyncService_ResponseAnswerDTO>required

Survey answers

Show child attributes

Response answer data.

question_idstringrequired

valueany

respondent_idstring | null

Respondent identifier

Show child attributes

Any of

string

null

interview_idstring | null

Interview execution ID

Show child attributes

Any of

string<uuid>

null

interview_ridstring | null

Allocated RID

Show child attributes

Any of

string

null

metadataobject | null

Additional metadata

Show child attributes

Any of

object

null

response_languagestring | null

Language code

Show child attributes

Any of

string

null

submission_modestring | nullcomplete

Submission mode: 'complete' or 'terminated_partial'

Show child attributes

Any of

string

null

duration_secondsinteger | null

Duration in seconds

Show child attributes

Any of

integer>= 0

null

sync_batch_idstring | null

Batch ID

Show child attributes

Any of

string<uuid>

null

Example

{
  "intent": "string",
  "idempotency_key": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "collected_at": "2024-01-15T09:30:00Z",
  "answers": [
    {
      "question_id": "string"
    }
  ],
  "respondent_id": "string",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_rid": "string",
  "metadata": {},
  "response_language": "string",
  "submission_mode": "complete",
  "duration_seconds": 0,
  "sync_batch_id": "550e8400-e29b-41d4-a716-446655440000"
}

SyncService_SyncReconciliationResponseDTO

object

Server-authorized reconciliation response.

statusstringrequired

'reconciled', 'duplicate', or 'rejected'

response_idstring | null

Persisted SurveyResponse ID in data-service

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Historical grant UUID that authorized this work

Show child attributes

Any of

string

null

reconciled_atstring | null

ISO timestamp when reconciliation completed

Show child attributes

Any of

string

null

reasonstring | null

Reason code if rejected (e.g. 'work_postdates_revocation', 'user_never_assigned')

Show child attributes

Any of

string

null

messagestringrequired

Human-readable status summary

SyncService_SyncStatusDTO

object

Sync status response.

device_idstringrequired

last_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

sync_statusstringrequired

last_survey_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

last_response_sync_atstring | null

Show child attributes

Any of

string<date-time>

null

sync_tokenstring | null

Show child attributes

Any of

string

null

surveys_syncedinteger0

responses_syncedinteger0

server_timestring | null

Show child attributes

Any of

string

null

server_time_offsetinteger | null0

Show child attributes

Any of

integer

null

rid_blocksArray<object>

Example

{
  "device_id": "string",
  "last_sync_at": "2024-01-15T09:30:00Z",
  "sync_status": "string",
  "last_survey_sync_at": "2024-01-15T09:30:00Z",
  "last_response_sync_at": "2024-01-15T09:30:00Z",
  "sync_token": "string",
  "surveys_synced": 0,
  "responses_synced": 0,
  "server_time": "string",
  "server_time_offset": 0,
  "rid_blocks": [
    {}
  ]
}

SyncService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

AnalyticsService_AggregateDataPointDTO

object

Single data point in aggregated results.

labelstringrequired

valuenumberrequired

countinteger | null

Show child attributes

Any of

integer

null

extraobject | null

Show child attributes

Any of

object

null

AnalyticsService_AggregateRequestDTO

object

Request to aggregate survey response data for a chart panel.

survey_idstringrequired

question_idsArray<string>required

chart_typestringrequired

aggregationstringrequired

filtersobject | null

Show child attributes

Any of

object

null

groupingstring | null

Show child attributes

Any of

string

null

value_modestring | null

Show child attributes

Any of

string

null

Example

{
  "survey_id": "string",
  "question_ids": [
    "string"
  ],
  "chart_type": "string",
  "aggregation": "string",
  "filters": {},
  "grouping": "string",
  "value_mode": "string"
}

AnalyticsService_AggregateResponseDTO

object

Aggregated chart data response.

survey_idstringrequired

question_idsArray<string>required

chart_typestringrequired

aggregationstringrequired

dataArray<AnalyticsService_AggregateDataPointDTO>required

Show child attributes

Single data point in aggregated results.

labelstringrequired

valuenumberrequired

countinteger | null

Show child attributes

Any of

integer

null

extraobject | null

Show child attributes

Any of

object

null

summaryobject | null

Show child attributes

Any of

object

null

cachedbooleanfalse

generated_atstring<date-time>required

Example

{
  "survey_id": "string",
  "question_ids": [
    "string"
  ],
  "chart_type": "string",
  "aggregation": "string",
  "data": [
    {
      "label": "string",
      "value": 0,
      "count": 0,
      "extra": {}
    }
  ],
  "summary": {},
  "cached": false,
  "generated_at": "2024-01-15T09:30:00Z"
}

AnalyticsService_AnalyticsResponseListDTO

object

Paginated list of survey responses for analytics.

itemsArray<object>required

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

AnalyticsService_AnalyticsSummaryDTO

object

Analytics summary.

total_surveysintegerrequired

total_responsesintegerrequired

active_surveysintegerrequired

completion_rate_avgnumberrequired

period_startstring<date-time>required

period_endstring<date-time>required

AnalyticsService_CreateDashboardDTO

object

Create dashboard request.

titlestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

is_defaultbooleanfalse

survey_idstring | null

Show child attributes

Any of

string

null

dashboard_typestring | null

Show child attributes

Any of

string

null

layout_configobject | null

Show child attributes

Any of

object

null

AnalyticsService_CreateWidgetDTO

object

Create widget request.

widget_typestringrequired

titlestringrequired

chart_typestringrequired

data_sourcestringsnapshot

query_configobject | null

Show child attributes

Any of

object

null

position_xinteger0

position_yinteger0

widthinteger4

heightinteger3

configobject | null

Show child attributes

Any of

object

null

filtersobject | null

Show child attributes

Any of

object

null

refresh_intervalinteger300

Example

{
  "widget_type": "string",
  "title": "string",
  "chart_type": "string",
  "data_source": "snapshot",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 4,
  "height": 3,
  "config": {},
  "filters": {},
  "refresh_interval": 300
}

AnalyticsService_DashboardListDTO

object

itemsArray<AnalyticsService_DashboardResponseDTO>required

Show child attributes

Dashboard response.

idstringrequired

titlestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_defaultbooleanrequired

layout_configobject | nullrequired

Show child attributes

Any of

object

null

created_bystringrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

widgetsArray<AnalyticsService_WidgetResponseDTO> | null

Show child attributes

Any of

Array<AnalyticsService_WidgetResponseDTO>

Show child attributes

Widget response.

idstringrequired

dashboard_idstringrequired

widget_typestringrequired

titlestringrequired

title_keystring | null

Show child attributes

Any of

string

null

chart_typestring | nullrequired

Show child attributes

Any of

string

null

data_sourcestring | nullrequired

Show child attributes

Any of

string

null

query_configobject | nullrequired

Show child attributes

Any of

object

null

position_xintegerrequired

position_yintegerrequired

widthintegerrequired

heightintegerrequired

configobject | nullrequired

Show child attributes

Any of

object

null

filtersobject | nullrequired

Show child attributes

Any of

object

null

refresh_intervalintegerrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

survey_idstring | null

Show child attributes

Any of

string

null

dashboard_typestring | null

Show child attributes

Any of

string

null

is_user_modifiedboolean | null

Show child attributes

Any of

boolean

null

generated_by_systemboolean | null

Show child attributes

Any of

boolean

null

source_survey_versionstring | null

Show child attributes

Any of

string

null

generator_versionstring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "is_default": true,
      "layout_config": {},
      "created_by": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "widgets": [
        {
          "id": "string",
          "dashboard_id": "string",
          "widget_type": "string",
          "title": "string",
          "title_key": "string",
          "chart_type": "string",
          "data_source": "string",
          "query_config": {},
          "position_x": 0,
          "position_y": 0,
          "width": 0,
          "height": 0,
          "config": {},
          "filters": {},
          "refresh_interval": 0,
          "created_at": "2024-01-15T09:30:00Z",
          "updated_at": "2024-01-15T09:30:00Z"
        }
      ],
      "survey_id": "string",
      "dashboard_type": "string",
      "is_user_modified": true,
      "generated_by_system": true,
      "source_survey_version": "string",
      "generator_version": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

AnalyticsService_DashboardResponseDTO

object

Dashboard response.

idstringrequired

titlestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

is_defaultbooleanrequired

layout_configobject | nullrequired

Show child attributes

Any of

object

null

created_bystringrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

widgetsArray<AnalyticsService_WidgetResponseDTO> | null

Show child attributes

Any of

Array<AnalyticsService_WidgetResponseDTO>

Show child attributes

Widget response.

idstringrequired

dashboard_idstringrequired

widget_typestringrequired

titlestringrequired

title_keystring | null

Show child attributes

Any of

string

null

chart_typestring | nullrequired

Show child attributes

Any of

string

null

data_sourcestring | nullrequired

Show child attributes

Any of

string

null

query_configobject | nullrequired

Show child attributes

Any of

object

null

position_xintegerrequired

position_yintegerrequired

widthintegerrequired

heightintegerrequired

configobject | nullrequired

Show child attributes

Any of

object

null

filtersobject | nullrequired

Show child attributes

Any of

object

null

refresh_intervalintegerrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

survey_idstring | null

Show child attributes

Any of

string

null

dashboard_typestring | null

Show child attributes

Any of

string

null

is_user_modifiedboolean | null

Show child attributes

Any of

boolean

null

generated_by_systemboolean | null

Show child attributes

Any of

boolean

null

source_survey_versionstring | null

Show child attributes

Any of

string

null

generator_versionstring | null

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "title": "string",
  "description": "string",
  "is_default": true,
  "layout_config": {},
  "created_by": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "widgets": [
    {
      "id": "string",
      "dashboard_id": "string",
      "widget_type": "string",
      "title": "string",
      "title_key": "string",
      "chart_type": "string",
      "data_source": "string",
      "query_config": {},
      "position_x": 0,
      "position_y": 0,
      "width": 0,
      "height": 0,
      "config": {},
      "filters": {},
      "refresh_interval": 0,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "survey_id": "string",
  "dashboard_type": "string",
  "is_user_modified": true,
  "generated_by_system": true,
  "source_survey_version": "string",
  "generator_version": "string"
}

AnalyticsService_DashboardSummaryDTO

object

Dashboard summary metrics.

tenant_idstringrequired

period_startstring<date-time>required

period_endstring<date-time>required

total_surveysintegerrequired

active_surveysintegerrequired

total_responsesintegerrequired

completion_rate_avgnumberrequired

average_response_timenumber | nullrequired

Show child attributes

Any of

number

null

responses_trendArray<object>required

top_surveysArray<object>required

generated_atstring<date-time>required

Example

{
  "tenant_id": "string",
  "period_start": "2024-01-15T09:30:00Z",
  "period_end": "2024-01-15T09:30:00Z",
  "total_surveys": 0,
  "active_surveys": 0,
  "total_responses": 0,
  "completion_rate_avg": 0,
  "average_response_time": 0,
  "responses_trend": [
    {}
  ],
  "top_surveys": [
    {}
  ],
  "generated_at": "2024-01-15T09:30:00Z"
}

AnalyticsService_GenerateDashboardRequestDTO

object

Request to generate a default dashboard for a survey.

survey_idstringrequired

AnalyticsService_GenerateDashboardResponseDTO

object

Response from dashboard generation.

dashboard_idstringrequired

statusstringrequired

widget_countintegerrequired

messagestringrequired

AnalyticsService_HTTPValidationError

object

detailArray<AnalyticsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

AnalyticsService_ResponseMetricsDTO

object

Response metrics for a date range.

datestringrequired

total_responsesintegerrequired

completed_responsesintegerrequired

completion_ratenumberrequired

average_duration_secondsnumber | nullrequired

Show child attributes

Any of

number

null

AnalyticsService_SurveyAnalyticsDTO

object

Survey analytics.

survey_idstringrequired

total_responsesintegerrequired

completion_ratenumberrequired

average_timenumber | nullrequired

Show child attributes

Any of

number

null

questions_countintegerrequired

responses_by_dateArray<object>required

AnalyticsService_SurveyPerformanceDTO

object

Survey performance metrics.

survey_idstringrequired

survey_namestringrequired

total_responsesintegerrequired

completion_ratenumberrequired

average_time_secondsnumber | nullrequired

Show child attributes

Any of

number

null

trendstringrequired

trend_percentagenumberrequired

AnalyticsService_UpdateDashboardDTO

object

Update dashboard request.

titlestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

is_defaultboolean | null

Show child attributes

Any of

boolean

null

layout_configobject | null

Show child attributes

Any of

object

null

is_user_modifiedboolean | null

Show child attributes

Any of

boolean

null

AnalyticsService_UpdateWidgetDTO

object

Update widget request.

titlestring | null

Show child attributes

Any of

string

null

chart_typestring | null

Show child attributes

Any of

string

null

data_sourcestring | null

Show child attributes

Any of

string

null

query_configobject | null

Show child attributes

Any of

object

null

position_xinteger | null

Show child attributes

Any of

integer

null

position_yinteger | null

Show child attributes

Any of

integer

null

widthinteger | null

Show child attributes

Any of

integer

null

heightinteger | null

Show child attributes

Any of

integer

null

configobject | null

Show child attributes

Any of

object

null

filtersobject | null

Show child attributes

Any of

object

null

refresh_intervalinteger | null

Show child attributes

Any of

integer

null

Example

{
  "title": "string",
  "chart_type": "string",
  "data_source": "string",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 0,
  "height": 0,
  "config": {},
  "filters": {},
  "refresh_interval": 0
}

AnalyticsService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

AnalyticsService_WidgetDataDTO

object

Widget data response.

widget_idstringrequired

data_sourcestringrequired

dataanyrequired

cachedbooleanfalse

generated_atstring<date-time>required

AnalyticsService_WidgetResponseDTO

object

Widget response.

idstringrequired

dashboard_idstringrequired

widget_typestringrequired

titlestringrequired

title_keystring | null

Show child attributes

Any of

string

null

chart_typestring | nullrequired

Show child attributes

Any of

string

null

data_sourcestring | nullrequired

Show child attributes

Any of

string

null

query_configobject | nullrequired

Show child attributes

Any of

object

null

position_xintegerrequired

position_yintegerrequired

widthintegerrequired

heightintegerrequired

configobject | nullrequired

Show child attributes

Any of

object

null

filtersobject | nullrequired

Show child attributes

Any of

object

null

refresh_intervalintegerrequired

created_atstring<date-time>required

updated_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

Example

{
  "id": "string",
  "dashboard_id": "string",
  "widget_type": "string",
  "title": "string",
  "title_key": "string",
  "chart_type": "string",
  "data_source": "string",
  "query_config": {},
  "position_x": 0,
  "position_y": 0,
  "width": 0,
  "height": 0,
  "config": {},
  "filters": {},
  "refresh_interval": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

WorkspaceService_HTTPValidationError

object

detailArray<WorkspaceService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

WorkspaceService_HealthResponseDTO

object

statusstringrequired

servicestringrequired

versionstringrequired

timestampstring<date-time>required

WorkspaceService_MemberAddDTO

object

user_idstringrequired

roleWorkspaceService_WorkspaceMemberRoleowneradmineditorviewerresponderviewer

WorkspaceService_MemberListDTO

object

itemsArray<WorkspaceService_MemberResponseDTO>required

Show child attributes

idstring<uuid>required

workspace_idstring<uuid>required

user_idstring<uuid>required

tenant_idstring<uuid>required

rolestringrequired

invited_bystring | nullrequired

Show child attributes

Any of

string<uuid>

null

joined_atstring<date-time>required

created_atstring<date-time>required

updated_atstring<date-time>required

user_emailstring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "role": "string",
      "invited_by": "550e8400-e29b-41d4-a716-446655440000",
      "joined_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "user_email": "string",
      "user_name": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

WorkspaceService_MemberResponseDTO

object

idstring<uuid>required

workspace_idstring<uuid>required

user_idstring<uuid>required

tenant_idstring<uuid>required

rolestringrequired

invited_bystring | nullrequired

Show child attributes

Any of

string<uuid>

null

joined_atstring<date-time>required

created_atstring<date-time>required

updated_atstring<date-time>required

user_emailstring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "string",
  "invited_by": "550e8400-e29b-41d4-a716-446655440000",
  "joined_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "user_email": "string",
  "user_name": "string"
}

WorkspaceService_MemberUpdateDTO

object

roleWorkspaceService_WorkspaceMemberRoleowneradmineditorviewerresponderrequired

WorkspaceService_ProjectCreateDTO

object

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

WorkspaceService_ProjectListDTO

object

itemsArray<WorkspaceService_ProjectResponseDTO>required

Show child attributes

idstring<uuid>required

workspace_idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

has_production_activitybooleanfalse

production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "description": "string",
      "status": "string",
      "has_production_activity": false,
      "production_activity_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

WorkspaceService_ProjectResponseDTO

object

idstring<uuid>required

workspace_idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

has_production_activitybooleanfalse

production_activity_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "has_production_activity": false,
  "production_activity_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

WorkspaceService_ProjectStatus

string

WorkspaceService_ProjectStatusdraftactivecompletedarchiveddeleted

WorkspaceService_ProjectUpdateDTO

object

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

statusWorkspaceService_ProjectStatus | null

Show child attributes

Any of

WorkspaceService_ProjectStatusdraftactivecompletedarchiveddeleted

null

WorkspaceService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

WorkspaceService_WorkspaceCreateDTO

object

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

WorkspaceService_WorkspaceListDTO

object

itemsArray<WorkspaceService_WorkspaceResponseDTO>required

Show child attributes

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "description": "string",
      "status": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "created_by": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

WorkspaceService_WorkspaceMemberRole

string

WorkspaceService_WorkspaceMemberRoleowneradmineditorviewerresponder

WorkspaceService_WorkspaceResponseDTO

object

idstring<uuid>required

tenant_idstring<uuid>required

namestringrequired

descriptionstring | nullrequired

Show child attributes

Any of

string

null

statusstringrequired

created_atstring<date-time>required

updated_atstring<date-time>required

created_bystring<uuid>required

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "description": "string",
  "status": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "created_by": "550e8400-e29b-41d4-a716-446655440000"
}

WorkspaceService_WorkspaceStatus

string

WorkspaceService_WorkspaceStatusactivearchivedsuspendeddeleted

WorkspaceService_WorkspaceUpdateDTO

object

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

statusWorkspaceService_WorkspaceStatus | null

Show child attributes

Any of

WorkspaceService_WorkspaceStatusactivearchivedsuspendeddeleted

null

WebhookService_CreateSubscriptionDTO

object

DTO for creating a webhook subscription.

namestringrequired

urlstringrequired

event_typesArray<string>required

survey_idstring | null

Show child attributes

Any of

string

null

project_idstring | null

Show child attributes

Any of

string

null

workspace_idstring | null

Show child attributes

Any of

string

null

secretstring | null

Show child attributes

Any of

string

null

WebhookService_DeliveryListDTO

object

DTO for list of webhook deliveries.

itemsArray<WebhookService_DeliveryResponseDTO>required

Show child attributes

DTO for webhook delivery response.

idstringrequired

subscription_idstringrequired

event_idstringrequired

event_typestringrequired

statusstringrequired

http_statusinteger | nullrequired

Show child attributes

Any of

integer

null

retry_countintegerrequired

attempted_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

delivered_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

error_messagestring | nullrequired

Show child attributes

Any of

string

null

created_atstring<date-time>required

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "subscription_id": "string",
      "event_id": "string",
      "event_type": "string",
      "status": "string",
      "http_status": 0,
      "retry_count": 0,
      "attempted_at": "2024-01-15T09:30:00Z",
      "delivered_at": "2024-01-15T09:30:00Z",
      "error_message": "string",
      "created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

WebhookService_DeliveryResponseDTO

object

DTO for webhook delivery response.

idstringrequired

subscription_idstringrequired

event_idstringrequired

event_typestringrequired

statusstringrequired

http_statusinteger | nullrequired

Show child attributes

Any of

integer

null

retry_countintegerrequired

attempted_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

delivered_atstring | nullrequired

Show child attributes

Any of

string<date-time>

null

error_messagestring | nullrequired

Show child attributes

Any of

string

null

created_atstring<date-time>required

Example

{
  "id": "string",
  "subscription_id": "string",
  "event_id": "string",
  "event_type": "string",
  "status": "string",
  "http_status": 0,
  "retry_count": 0,
  "attempted_at": "2024-01-15T09:30:00Z",
  "delivered_at": "2024-01-15T09:30:00Z",
  "error_message": "string",
  "created_at": "2024-01-15T09:30:00Z"
}

WebhookService_HTTPValidationError

object

detailArray<WebhookService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

WebhookService_SubscriptionListDTO

object

DTO for list of webhook subscriptions.

itemsArray<WebhookService_SubscriptionResponseDTO>required

Show child attributes

DTO for webhook subscription response.

idstringrequired

namestringrequired

urlstringrequired

event_typesArray<string>required

survey_idstring | nullrequired

Show child attributes

Any of

string

null

project_idstring | nullrequired

Show child attributes

Any of

string

null

workspace_idstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

created_atstring<date-time>required

updated_atstring<date-time>required

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "url": "string",
      "event_types": [
        "string"
      ],
      "survey_id": "string",
      "project_id": "string",
      "workspace_id": "string",
      "is_active": true,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

WebhookService_SubscriptionResponseDTO

object

DTO for webhook subscription response.

idstringrequired

namestringrequired

urlstringrequired

event_typesArray<string>required

survey_idstring | nullrequired

Show child attributes

Any of

string

null

project_idstring | nullrequired

Show child attributes

Any of

string

null

workspace_idstring | nullrequired

Show child attributes

Any of

string

null

is_activebooleanrequired

created_atstring<date-time>required

updated_atstring<date-time>required

Example

{
  "id": "string",
  "name": "string",
  "url": "string",
  "event_types": [
    "string"
  ],
  "survey_id": "string",
  "project_id": "string",
  "workspace_id": "string",
  "is_active": true,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

WebhookService_UpdateSubscriptionDTO

object

DTO for updating a webhook subscription.

namestring | null

Show child attributes

Any of

string

null

urlstring | null

Show child attributes

Any of

string

null

event_typesArray<string> | null

Show child attributes

Any of

Array<string>

null

is_activeboolean | null

Show child attributes

Any of

boolean

null

WebhookService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

OdkBridge_Body_submit_form_submission_post

object

xml_submission_filestringrequired

attachmentsArray<string>

OdkBridge_HTTPValidationError

object

detailArray<OdkBridge_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

OdkBridge_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

FormService_BatchNoteCreateDto

object

notesArray<FormService_NoteCreateDto>required

Show child attributes

field_namestring | null

Show child attributes

Any of

string

null

textstringrequired

categorystringgeneral

client_created_atstring | null

Show child attributes

Any of

string<date-time>

null

FormService_CreateInterviewDto

object

survey_idstring<uuid>required

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

total_questionsinteger0

languagestring | null

Active language code during interview (e.g., 'en', 'es', 'hi')

Show child attributes

Any of

string

null

interview_metadataobject[object Object]

survey_namestring | null

Show child attributes

Any of

string

null

response_ridstring | null

Show child attributes

Any of

string

null

Example

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "total_questions": 0,
  "language": "string",
  "interview_metadata": {},
  "survey_name": "string",
  "response_rid": "string"
}

FormService_DraftConflictResponse

object

Response returned upon an optimistic concurrency conflict (HTTP 409).

errorstringDRAFT_CONFLICT

messagestringrequired

draft_idstring<uuid>required

server_version_tokenintegerrequired

client_version_tokeninteger | null

Show child attributes

Any of

integer

null

server_content_hashstring | null

Show child attributes

Any of

string

null

client_content_hashstring | null

Show child attributes

Any of

string

null

server_device_idstring | null

Show child attributes

Any of

string

null

server_updated_atstringrequired

server_draft_dataobjectrequired

Example

{
  "error": "DRAFT_CONFLICT",
  "message": "string",
  "draft_id": "550e8400-e29b-41d4-a716-446655440000",
  "server_version_token": 0,
  "client_version_token": 0,
  "server_content_hash": "string",
  "client_content_hash": "string",
  "server_device_id": "string",
  "server_updated_at": "string",
  "server_draft_data": {}
}

FormService_DraftCreateRequest

object

Request to create a new draft.

idstring | null

Show child attributes

Any of

string<uuid>

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobject

current_pageinteger0

survey_version_idstring | null

Pinned immutable survey schema version ID

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "content_hash": "string",
  "idempotency_key": "string"
}

FormService_DraftDeltaResponse

object

Response containing delta sync drafts since cursor.

itemsArray<FormService_DraftResponse>required

Show child attributes

Response containing draft information.

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

user_idstring | null

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobjectrequired

current_pageintegerrequired

completed_fields_countintegerrequired

total_fields_countinteger | null

Show child attributes

Any of

integer

null

completion_percentageintegerrequired

statusstringrequired

version_tokeninteger1

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

deleted_atstring | null

Show child attributes

Any of

string<date-time>

null

validation_errorsArray<object>

is_auto_savedbooleanfalse

reconciliation_grant_idstring | null

Show child attributes

Any of

string<uuid>

null

reconciled_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

server_timestampstringrequired

totalintegerrequired

has_nextbooleanrequired

next_cursorstring | null

Show child attributes

Any of

string

null

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "device_id": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "draft_data": {},
      "current_page": 0,
      "completed_fields_count": 0,
      "total_fields_count": 0,
      "completion_percentage": 0,
      "status": "string",
      "version_token": 1,
      "content_hash": "string",
      "idempotency_key": "string",
      "is_deleted": false,
      "deleted_at": "2024-01-15T09:30:00Z",
      "validation_errors": [],
      "is_auto_saved": false,
      "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
      "reconciled_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "expires_at": "2024-01-15T09:30:00Z"
    }
  ],
  "server_timestamp": "string",
  "total": 0,
  "has_next": true,
  "next_cursor": "string"
}

FormService_DraftDrainRevokedRequest

object

Request to drain an offline draft whose user's assignment was revoked.

idstring<uuid>required

Unique draft identifier

survey_idstring<uuid>required

Survey identifier

survey_version_idstring | null

Pinned survey schema version ID

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobject

Answers captured in draft

current_pageinteger0

device_idstringrequired

Attribution device ID (must not be placeholder)

version_tokeninteger>= 11

Client version token

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

reconciliation_grant_idstring | null

Reconciliation grant ID

Show child attributes

Any of

string<uuid>

null

lastModifiedAtstring<date-time>required

Timestamp of the last offline edit to the draft

reconciliation_reasonstring | null

Optional domain note or reason

Show child attributes

Any of

string

null

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "device_id": "string",
  "version_token": 1,
  "content_hash": "string",
  "idempotency_key": "string",
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "lastModifiedAt": "2024-01-15T09:30:00Z",
  "reconciliation_reason": "string"
}

FormService_DraftListResponse

object

Response containing list of drafts.

itemsArray<FormService_DraftResponse>required

Show child attributes

Response containing draft information.

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

user_idstring | null

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobjectrequired

current_pageintegerrequired

completed_fields_countintegerrequired

total_fields_countinteger | null

Show child attributes

Any of

integer

null

completion_percentageintegerrequired

statusstringrequired

version_tokeninteger1

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

deleted_atstring | null

Show child attributes

Any of

string<date-time>

null

validation_errorsArray<object>

is_auto_savedbooleanfalse

reconciliation_grant_idstring | null

Show child attributes

Any of

string<uuid>

null

reconciled_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

totalintegerrequired

skipinteger0

limitinteger20

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "device_id": "string",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "string",
      "draft_data": {},
      "current_page": 0,
      "completed_fields_count": 0,
      "total_fields_count": 0,
      "completion_percentage": 0,
      "status": "string",
      "version_token": 1,
      "content_hash": "string",
      "idempotency_key": "string",
      "is_deleted": false,
      "deleted_at": "2024-01-15T09:30:00Z",
      "validation_errors": [],
      "is_auto_saved": false,
      "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
      "reconciled_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "expires_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 20,
  "has_next": true,
  "has_previous": true
}

FormService_DraftResponse

object

Response containing draft information.

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

user_idstring | null

Show child attributes

Any of

string<uuid>

null

device_idstring | null

Show child attributes

Any of

string

null

survey_idstring<uuid>required

session_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

namestring | null

Show child attributes

Any of

string

null

draft_dataobjectrequired

current_pageintegerrequired

completed_fields_countintegerrequired

total_fields_countinteger | null

Show child attributes

Any of

integer

null

completion_percentageintegerrequired

statusstringrequired

version_tokeninteger1

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

is_deletedbooleanfalse

deleted_atstring | null

Show child attributes

Any of

string<date-time>

null

validation_errorsArray<object>

is_auto_savedbooleanfalse

reconciliation_grant_idstring | null

Show child attributes

Any of

string<uuid>

null

reconciled_atstring | null

Show child attributes

Any of

string<date-time>

null

created_atstring<date-time>required

updated_atstring<date-time>required

expires_atstring | null

Show child attributes

Any of

string<date-time>

null

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "string",
  "draft_data": {},
  "current_page": 0,
  "completed_fields_count": 0,
  "total_fields_count": 0,
  "completion_percentage": 0,
  "status": "string",
  "version_token": 1,
  "content_hash": "string",
  "idempotency_key": "string",
  "is_deleted": false,
  "deleted_at": "2024-01-15T09:30:00Z",
  "validation_errors": [],
  "is_auto_saved": false,
  "reconciliation_grant_id": "550e8400-e29b-41d4-a716-446655440000",
  "reconciled_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z"
}

FormService_DraftUpdateRequest

object

Request to update an existing draft.

draft_dataobject | null

Show child attributes

Any of

object

null

namestring | null

Show child attributes

Any of

string

null

current_pageinteger | null

Show child attributes

Any of

integer

null

is_auto_savebooleanfalse

version_tokeninteger>= 11

Expected current server version token

device_idstring | null

Show child attributes

Any of

string

null

content_hashstring | null

Show child attributes

Any of

string

null

idempotency_keystring | null

Show child attributes

Any of

string

null

Example

{
  "draft_data": {},
  "name": "string",
  "current_page": 0,
  "is_auto_save": false,
  "version_token": 1,
  "device_id": "string",
  "content_hash": "string",
  "idempotency_key": "string"
}

FormService_EvaluateExpressionRequest

object

Request to evaluate an XPath expression.

session_tokenstringrequired

Form session token

expressionstringrequired

XPath expression to evaluate

form_dataobject

Form data for variable resolution

FormService_EvaluateExpressionResponse

object

Response for expression evaluation.

successbooleanrequired

resultany

errorstring | null

Show child attributes

Any of

string

null

FormService_FormManifestResponse

object

Response for offline form manifest.

survey_idstring<uuid>required

version_idstring | null

Show child attributes

Any of

string<uuid>

null

manifest_versionstringrequired

form_filesArray<object>required

Show child attributes

[key: string]string

media_filesArray<object>required

Show child attributes

[key: string]string

last_updatedstring<date-time>required

Example

{
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "manifest_version": "string",
  "form_files": [
    {}
  ],
  "media_files": [
    {}
  ],
  "last_updated": "2024-01-15T09:30:00Z"
}

FormService_FormRenderResponse

object

Response containing rendered form data.

session_idstring<uuid>required

session_tokenstringrequired

survey_idstring<uuid>required

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

form_schemaobjectrequired

form_htmlstring | null

Show child attributes

Any of

string

null

prefill_dataobject | null

Show child attributes

Any of

object

null

total_pagesintegerrequired

current_pageinteger0

expires_atstring<date-time>required

supports_offlinebooleanfalse

lookup_dataobject | null

Show child attributes

Any of

[key: string]object

Show child attributes

[key: string]object

null

trigger_questionsArray<string>

referee_questionsobject[object Object]

Show child attributes

[key: string]Array<string>

Example

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "form_schema": {},
  "form_html": "string",
  "prefill_data": {},
  "total_pages": 0,
  "current_page": 0,
  "expires_at": "2024-01-15T09:30:00Z",
  "supports_offline": false,
  "lookup_data": {},
  "trigger_questions": [],
  "referee_questions": {}
}

FormService_FormSubmitRequest

object

Request to submit a completed form.

session_tokenstringrequired

form_dataobjectrequired

is_completebooleantrue

current_pageinteger | null

Show child attributes

Any of

integer

null

client_timestampstring | null

Show child attributes

Any of

string<date-time>

null

duration_secondsinteger | null

Active form filling duration in seconds, excluding paused time

Show child attributes

Any of

integer[0, 2592000]

null

offline_submissionbooleanfalse

offline_queued_atstring | null

Show child attributes

Any of

string<date-time>

null

edit_response_idstring | null

Show child attributes

Any of

string

null

version_idstring | null

Show child attributes

Any of

string<uuid>

null

interview_idstring | null

Interview execution ID (cross-service correlation)

Show child attributes

Any of

string<uuid>

null

languagestring | null

Language code used for this submission (e.g., 'en', 'es', 'fr')

Show child attributes

Any of

string

null

Example

{
  "session_token": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "client_timestamp": "2024-01-15T09:30:00Z",
  "duration_seconds": 0,
  "offline_submission": false,
  "offline_queued_at": "2024-01-15T09:30:00Z",
  "edit_response_id": "string",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "language": "string"
}

FormService_FormSubmitResponse

object

Response after form submission.

successbooleanrequired

response_idstring | null

Show child attributes

Any of

string<uuid>

null

session_idstring<uuid>required

version_idstring | null

Show child attributes

Any of

string<uuid>

null

submitted_atstring<date-time>required

validation_errorsArray<object>

messagestring | null

Show child attributes

Any of

string

null

response_languagestring | null

Show child attributes

Any of

string

null

Example

{
  "success": true,
  "response_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "version_id": "550e8400-e29b-41d4-a716-446655440000",
  "submitted_at": "2024-01-15T09:30:00Z",
  "validation_errors": [],
  "message": "string",
  "response_language": "string"
}

FormService_FormValidateRequest

object

Request to validate form data without submitting.

session_tokenstringrequired

form_dataobjectrequired

validate_allbooleanfalse

fields_to_validateArray<string> | null

Show child attributes

Any of

Array<string>

null

FormService_FormValidateResponse

object

Response with validation results.

is_validbooleanrequired

errorsArray<object>

warningsArray<object>

completion_percentageinteger0

FormService_HTTPValidationError

object

detailArray<FormService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

FormService_InterviewDto

object

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_idstring<uuid>required

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

interviewer_idstring | null

Show child attributes

Any of

string<uuid>

null

session_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

started_atstring | null

Show child attributes

Any of

string<date-time>

null

paused_atstring | null

Show child attributes

Any of

string<date-time>

null

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

terminated_atstring | null

Show child attributes

Any of

string<date-time>

null

termination_reasonstring | null

Show child attributes

Any of

string

null

last_heartbeat_atstring | null

Show child attributes

Any of

string<date-time>

null

languagestring | null

Show child attributes

Any of

string

null

interview_metadataobject[object Object]

current_pageinteger0

answered_countinteger0

total_questionsinteger0

survey_namestring | null

Show child attributes

Any of

string

null

response_ridstring | null

Show child attributes

Any of

string

null

response_uidstring | null

Show child attributes

Any of

string

null

current_response_idstring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

updated_atstring<date-time>required

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
  "interviewer_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "status": "string",
  "started_at": "2024-01-15T09:30:00Z",
  "paused_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "terminated_at": "2024-01-15T09:30:00Z",
  "termination_reason": "string",
  "last_heartbeat_at": "2024-01-15T09:30:00Z",
  "language": "string",
  "interview_metadata": {},
  "current_page": 0,
  "answered_count": 0,
  "total_questions": 0,
  "survey_name": "string",
  "response_rid": "string",
  "response_uid": "string",
  "current_response_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

FormService_InterviewEventDto

object

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

from_statusstring | null

Show child attributes

Any of

string

null

to_statusstringrequired

triggered_bystring | null

Show child attributes

Any of

string<uuid>

null

event_metadataobject[object Object]

created_atstring<date-time>required

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "from_status": "string",
  "to_status": "string",
  "triggered_by": "550e8400-e29b-41d4-a716-446655440000",
  "event_metadata": {},
  "created_at": "2024-01-15T09:30:00Z"
}

FormService_InterviewListResponse

object

itemsArray<FormService_InterviewDto>required

Show child attributes

idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

survey_idstring<uuid>required

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

interviewer_idstring | null

Show child attributes

Any of

string<uuid>

null

session_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

started_atstring | null

Show child attributes

Any of

string<date-time>

null

paused_atstring | null

Show child attributes

Any of

string<date-time>

null

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

terminated_atstring | null

Show child attributes

Any of

string<date-time>

null

termination_reasonstring | null

Show child attributes

Any of

string

null

last_heartbeat_atstring | null

Show child attributes

Any of

string<date-time>

null

languagestring | null

Show child attributes

Any of

string

null

interview_metadataobject[object Object]

current_pageinteger0

answered_countinteger0

total_questionsinteger0

survey_namestring | null

Show child attributes

Any of

string

null

response_ridstring | null

Show child attributes

Any of

string

null

response_uidstring | null

Show child attributes

Any of

string

null

current_response_idstring | null

Show child attributes

Any of

string<uuid>

null

created_atstring<date-time>required

updated_atstring<date-time>required

totalintegerrequired

skipinteger0

limitinteger20

has_nextbooleanfalse

has_previousbooleanfalse

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "respondent_id": "550e8400-e29b-41d4-a716-446655440000",
      "interviewer_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_token": "string",
      "status": "string",
      "started_at": "2024-01-15T09:30:00Z",
      "paused_at": "2024-01-15T09:30:00Z",
      "completed_at": "2024-01-15T09:30:00Z",
      "terminated_at": "2024-01-15T09:30:00Z",
      "termination_reason": "string",
      "last_heartbeat_at": "2024-01-15T09:30:00Z",
      "language": "string",
      "interview_metadata": {},
      "current_page": 0,
      "answered_count": 0,
      "total_questions": 0,
      "survey_name": "string",
      "response_rid": "string",
      "response_uid": "string",
      "current_response_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 20,
  "has_next": false,
  "has_previous": false
}

FormService_NoteCreateDto

object

field_namestring | null

Show child attributes

Any of

string

null

textstringrequired

categorystringgeneral

client_created_atstring | null

Show child attributes

Any of

string<date-time>

null

FormService_NoteListResponse

object

itemsArray<FormService_NoteResponseDto>required

Show child attributes

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

field_namestring | null

Show child attributes

Any of

string

null

textstringrequired

categorystringrequired

author_idstring | null

Show child attributes

Any of

string<uuid>

null

pinnedbooleanfalse

created_atstring<date-time>required

updated_atstring<date-time>required

client_created_atstring | null

Show child attributes

Any of

string<date-time>

null

totalintegerrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "interview_id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "field_name": "string",
      "text": "string",
      "category": "string",
      "author_id": "550e8400-e29b-41d4-a716-446655440000",
      "pinned": false,
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "client_created_at": "2024-01-15T09:30:00Z"
    }
  ],
  "total": 0
}

FormService_NoteResponseDto

object

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

field_namestring | null

Show child attributes

Any of

string

null

textstringrequired

categorystringrequired

author_idstring | null

Show child attributes

Any of

string<uuid>

null

pinnedbooleanfalse

created_atstring<date-time>required

updated_atstring<date-time>required

client_created_atstring | null

Show child attributes

Any of

string<date-time>

null

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "field_name": "string",
  "text": "string",
  "category": "string",
  "author_id": "550e8400-e29b-41d4-a716-446655440000",
  "pinned": false,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "client_created_at": "2024-01-15T09:30:00Z"
}

FormService_NoteUpdateDto

object

textstring | null

Show child attributes

Any of

string

null

categorystring | null

Show child attributes

Any of

string

null

pinnedboolean | null

Show child attributes

Any of

boolean

null

field_namestring | null

Show child attributes

Any of

string

null

FormService_PrefillResponse

object

Response containing pre-fill data from a previous response.

prefill_dataobject

Field name to value mapping for pre-fill

source_response_idstringrequired

ID of the source response

source_submitted_atstring | null

When the source response was submitted

Show child attributes

Any of

string

null

prefill_fieldsArray<string>

List of field names that were pre-filled

FormService_RidBlockAllocationRequest

object

Request payload for server-allocated device-bound RID block (R25 / AD-3).

survey_idstring<uuid>required

ID of the survey for which RID block is requested

device_idstringrequired

Unique client device ID (non-placeholder)

block_sizeinteger[1, 200]50

Number of sequential RIDs to allocate

idempotency_keystring | null

Client idempotency key for safe retries

Show child attributes

Any of

string

null

FormService_RidBlockListResponse

object

List of RID block allocations.

itemsArray<FormService_RidBlockResponse>required

Show child attributes

Server-allocated device-bound RID block response (matches mobile RidBlockDto).

idstring<uuid>required

tenant_idstring<uuid>required

survey_idstring<uuid>required

user_idstring<uuid>required

user_codestringrequired

device_idstringrequired

start_seqintegerrequired

end_seqintegerrequired

current_seqintegerrequired

is_exhaustedbooleanfalse

idempotency_keystring | null

Show child attributes

Any of

string

null

created_atstringrequired

totalintegerrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_code": "string",
      "device_id": "string",
      "start_seq": 0,
      "end_seq": 0,
      "current_seq": 0,
      "is_exhausted": false,
      "idempotency_key": "string",
      "created_at": "string"
    }
  ],
  "total": 0
}

FormService_RidBlockResponse

object

Server-allocated device-bound RID block response (matches mobile RidBlockDto).

idstring<uuid>required

tenant_idstring<uuid>required

survey_idstring<uuid>required

user_idstring<uuid>required

user_codestringrequired

device_idstringrequired

start_seqintegerrequired

end_seqintegerrequired

current_seqintegerrequired

is_exhaustedbooleanfalse

idempotency_keystring | null

Show child attributes

Any of

string

null

created_atstringrequired

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_code": "string",
  "device_id": "string",
  "start_seq": 0,
  "end_seq": 0,
  "current_seq": 0,
  "is_exhausted": false,
  "idempotency_key": "string",
  "created_at": "string"
}

FormService_SessionListResponse

object

Response containing list of sessions.

itemsArray<FormService_SessionResponse>required

Show child attributes

Response containing session information.

idstring<uuid>required

survey_idstring<uuid>required

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

current_pageintegerrequired

total_pagesinteger | null

Show child attributes

Any of

integer

null

progress_percentageintegerrequired

is_offlinebooleanrequired

started_atstring<date-time>required

last_activity_atstring<date-time>required

expires_atstring<date-time>required

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

response_idstring | null

Show child attributes

Any of

string<uuid>

null

metadataobject[object Object]

totalintegerrequired

skipinteger0

limitinteger20

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_id": "550e8400-e29b-41d4-a716-446655440000",
      "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
      "session_token": "string",
      "status": "string",
      "current_page": 0,
      "total_pages": 0,
      "progress_percentage": 0,
      "is_offline": true,
      "started_at": "2024-01-15T09:30:00Z",
      "last_activity_at": "2024-01-15T09:30:00Z",
      "expires_at": "2024-01-15T09:30:00Z",
      "completed_at": "2024-01-15T09:30:00Z",
      "response_id": "550e8400-e29b-41d4-a716-446655440000",
      "metadata": {}
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 20,
  "has_next": true,
  "has_previous": true
}

FormService_SessionResponse

object

Response containing session information.

idstring<uuid>required

survey_idstring<uuid>required

survey_version_idstring | null

Show child attributes

Any of

string<uuid>

null

session_tokenstringrequired

statusstringrequired

current_pageintegerrequired

total_pagesinteger | null

Show child attributes

Any of

integer

null

progress_percentageintegerrequired

is_offlinebooleanrequired

started_atstring<date-time>required

last_activity_atstring<date-time>required

expires_atstring<date-time>required

completed_atstring | null

Show child attributes

Any of

string<date-time>

null

response_idstring | null

Show child attributes

Any of

string<uuid>

null

metadataobject[object Object]

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_id": "550e8400-e29b-41d4-a716-446655440000",
  "survey_version_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_token": "string",
  "status": "string",
  "current_page": 0,
  "total_pages": 0,
  "progress_percentage": 0,
  "is_offline": true,
  "started_at": "2024-01-15T09:30:00Z",
  "last_activity_at": "2024-01-15T09:30:00Z",
  "expires_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z",
  "response_id": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {}
}

FormService_TerminationDto

object

idstring<uuid>required

interview_idstring<uuid>required

tenant_idstring | null

Show child attributes

Any of

string<uuid>

null

termination_reasonstringrequired

explanatory_textstring | null

Show child attributes

Any of

string

null

retain_partial_databooleanrequired

discard_databooleanrequired

notify_supervisorbooleanrequired

supervisor_notifiedbooleanrequired

supervisor_notified_atstring | null

Show child attributes

Any of

string<date-time>

null

data_action_takenstring | null

Show child attributes

Any of

string

null

terminated_bystring<uuid>required

created_atstring<date-time>required

Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "interview_id": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "termination_reason": "string",
  "explanatory_text": "string",
  "retain_partial_data": true,
  "discard_data": true,
  "notify_supervisor": true,
  "supervisor_notified": true,
  "supervisor_notified_at": "2024-01-15T09:30:00Z",
  "data_action_taken": "string",
  "terminated_by": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T09:30:00Z"
}

FormService_TerminationPolicyDto

object

retain_partial_databooleanrequired

discard_databooleanrequired

notify_supervisorbooleanrequired

requires_explanatory_textbooleanrequired

FormService_TerminationReasonOptionDto

object

codestringrequired

display_labelstringrequired

policyFormService_TerminationPolicyDtorequired

Show child attributes

retain_partial_databooleanrequired

discard_databooleanrequired

notify_supervisorbooleanrequired

requires_explanatory_textbooleanrequired

Example

{
  "code": "string",
  "display_label": "string",
  "policy": {
    "retain_partial_data": true,
    "discard_data": true,
    "notify_supervisor": true,
    "requires_explanatory_text": true
  }
}

FormService_TransitionInterviewDto

object

to_statusstringrequired

termination_reasonstring | null

Show child attributes

Any of

string

null

explanatory_textstring | null

Show child attributes

Any of

string

null

form_dataobject | null

Show child attributes

Any of

object

null

is_completeboolean | null

Show child attributes

Any of

boolean

null

current_pageinteger | null

Show child attributes

Any of

integer

null

version_idstring | null

Show child attributes

Any of

string

null

edit_response_idstring | null

Show child attributes

Any of

string

null

duration_secondsinteger | null

Show child attributes

Any of

integer

null

question_paradataobject | null

Show child attributes

Any of

object

null

Example

{
  "to_status": "string",
  "termination_reason": "string",
  "explanatory_text": "string",
  "form_data": {},
  "is_complete": true,
  "current_page": 0,
  "version_id": "string",
  "edit_response_id": "string",
  "duration_seconds": 0,
  "question_paradata": {}
}

FormService_UpdateInterviewDto

object

respondent_idstring | null

Show child attributes

Any of

string<uuid>

null

current_pageinteger | null

Show child attributes

Any of

integer

null

answered_countinteger | null

Show child attributes

Any of

integer

null

total_questionsinteger | null

Show child attributes

Any of

integer

null

interview_metadataobject | null

Show child attributes

Any of

object

null

FormService_ValidateFieldRequest

object

Request to validate a single field.

session_tokenstringrequired

Form session token

field_namestringrequired

Name of the field to validate

field_valueanyrequired

Current value of the field

form_dataobject

Complete form data

FormService_ValidateFieldResponse

object

Response for single field validation.

is_validbooleanrequired

fieldstringrequired

errorsArray<object>

FormService_ValidateFormRequest

object

Request to validate entire form.

session_tokenstringrequired

Form session token

form_dataobjectrequired

Form data to validate

fields_to_validateArray<string> | null

Optional list of fields to validate (all if not specified)

Show child attributes

Any of

Array<string>

null

FormService_ValidateFormResponse

object

Response for form validation.

is_validbooleanrequired

errorsArray<object>

total_fieldsintegerrequired

valid_fieldsintegerrequired

invalid_fieldsintegerrequired

FormService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

MediaService_AssetUpdateRequest

object

original_filenamestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

alt_textstring | null

Show child attributes

Any of

string

null

tagsArray<string> | null

Show child attributes

Any of

Array<string>

null

is_publicboolean | null

Show child attributes

Any of

boolean

null

MediaService_Body_upload_batch_api_v1_media_upload_batch_post

object

filesArray<string>required

survey_idstring | null

Show child attributes

Any of

string

null

response_idstring | null

Show child attributes

Any of

string

null

entity_typestring | null

Show child attributes

Any of

string

null

entity_idstring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

device_idstring | null

Device that recorded this media (used for post-closure grant validation)

Show child attributes

Any of

string

null

Example

{
  "files": [
    "string"
  ],
  "survey_id": "string",
  "response_id": "string",
  "entity_type": "string",
  "entity_id": "string",
  "user_name": "string",
  "device_id": "string"
}

MediaService_Body_upload_chunk_api_v1_media_upload_chunk_post

object

filestringrequired

upload_idstringrequired

Client-generated stable upload ID (media local ID)

chunk_indexinteger>= 0required

Zero-based chunk index

total_chunksinteger[1, 100000]required

Total number of chunks

file_namestringrequired

mime_typestringrequired

survey_idstring | null

Survey this media belongs to (REQUIRED for production-bound uploads)

Show child attributes

Any of

string

null

response_idstring | null

Client-local response reference (metadata only — never the enforcement key)

Show child attributes

Any of

string

null

checksumstring | null

Expected SHA-256 of the FULL assembled file

Show child attributes

Any of

string

null

device_idstring | null

Device that recorded this media (used for post-closure grant validation)

Show child attributes

Any of

string

null

Example

{
  "file": "string",
  "upload_id": "string",
  "chunk_index": 0,
  "total_chunks": 1,
  "file_name": "string",
  "mime_type": "string",
  "survey_id": "string",
  "response_id": "string",
  "checksum": "string",
  "device_id": "string"
}

MediaService_Body_upload_file_api_v1_media_upload_post

object

filestringrequired

survey_idstring | null

Show child attributes

Any of

string

null

response_idstring | null

Show child attributes

Any of

string

null

entity_typestring | null

Show child attributes

Any of

string

null

entity_idstring | null

Show child attributes

Any of

string

null

is_publicbooleanfalse

descriptionstring | null

Show child attributes

Any of

string

null

survey_namestring | null

Show child attributes

Any of

string

null

question_namestring | null

Show child attributes

Any of

string

null

user_namestring | null

Show child attributes

Any of

string

null

device_idstring | null

Device that recorded this media (used for post-closure grant validation)

Show child attributes

Any of

string

null

checksumstring | null

Expected SHA-256 checksum of file

Show child attributes

Any of

string

null

Example

{
  "file": "string",
  "survey_id": "string",
  "response_id": "string",
  "entity_type": "string",
  "entity_id": "string",
  "is_public": false,
  "description": "string",
  "survey_name": "string",
  "question_name": "string",
  "user_name": "string",
  "device_id": "string",
  "checksum": "string"
}

MediaService_Body_upload_library_file_api_v1_media_library_upload_post

object

filestringrequired

Media file to add to the library

descriptionstring | null

Optional description

Show child attributes

Any of

string

null

survey_namestring | null

Optional survey name for renaming

Show child attributes

Any of

string

null

question_namestring | null

Optional question name for renaming

Show child attributes

Any of

string

null

response_idstring | null

Optional response ID for renaming

Show child attributes

Any of

string

null

MediaService_Body_upload_library_files_batch_api_v1_media_library_upload_batch_post

object

filesArray<string>required

Media files to add to the library

MediaService_HTTPValidationError

object

detailArray<MediaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

MediaService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

NotificationService_AWSConfig

object

aws_regionstring | null

Show child attributes

Any of

string

null

aws_access_key_idstring | null

Show child attributes

Any of

string

null

aws_secret_access_keystring | null

Show child attributes

Any of

string

null

aws_origination_numberstring | null

Show child attributes

Any of

string

null

NotificationService_AWSConfigResponse

object

aws_regionstring | null

Show child attributes

Any of

string

null

aws_access_key_idstring | null••••••••

Show child attributes

Any of

string

null

aws_secret_access_keystring | null••••••••

Show child attributes

Any of

string

null

aws_origination_numberstring | null

Show child attributes

Any of

string

null

NotificationService_AfricasTalkingConfig

object

africas_talking_usernamestring | null

Show child attributes

Any of

string

null

africas_talking_api_keystring | null

Show child attributes

Any of

string

null

africas_talking_shortcodestring | null

Show child attributes

Any of

string

null

NotificationService_AfricasTalkingConfigResponse

object

africas_talking_usernamestring | null

Show child attributes

Any of

string

null

africas_talking_api_keystring | null••••••••

Show child attributes

Any of

string

null

africas_talking_shortcodestring | null

Show child attributes

Any of

string

null

NotificationService_CancelNotificationsRequest

object

recipientstring<email>required

NotificationService_GenericHttpConfig

object

generic_sms_endpointstring | null

Show child attributes

Any of

string

null

generic_sms_methodstringPOSTGETPOST

generic_sms_auth_header_namestring | null

Show child attributes

Any of

string

null

generic_sms_auth_header_valuestring | null

Show child attributes

Any of

string

null

generic_sms_body_templatestring | null

Show child attributes

Any of

string

null

Example

{
  "generic_sms_endpoint": "string",
  "generic_sms_method": "POST",
  "generic_sms_auth_header_name": "string",
  "generic_sms_auth_header_value": "string",
  "generic_sms_body_template": "string"
}

NotificationService_GenericHttpConfigResponse

object

generic_sms_endpointstring | null

Show child attributes

Any of

string

null

generic_sms_methodstring | null

Show child attributes

Any of

string

null

generic_sms_auth_header_namestring | null

Show child attributes

Any of

string

null

generic_sms_auth_header_valuestring | null••••••••

Show child attributes

Any of

string

null

generic_sms_body_templatestring | null

Show child attributes

Any of

string

null

Example

{
  "generic_sms_endpoint": "string",
  "generic_sms_method": "string",
  "generic_sms_auth_header_name": "string",
  "generic_sms_auth_header_value": "••••••••",
  "generic_sms_body_template": "string"
}

NotificationService_HTTPValidationError

object

detailArray<NotificationService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

NotificationService_KaleyraConfig

object

kaleyra_api_keystring | null

Show child attributes

Any of

string

null

kaleyra_account_sidstring | null

Show child attributes

Any of

string

null

kaleyra_sender_idstring | null

Show child attributes

Any of

string

null

NotificationService_KaleyraConfigResponse

object

kaleyra_api_keystring | null••••••••

Show child attributes

Any of

string

null

kaleyra_account_sidstring | null

Show child attributes

Any of

string

null

kaleyra_sender_idstring | null

Show child attributes

Any of

string

null

NotificationService_MSG91Config

object

msg91_api_keystring | null

Show child attributes

Any of

string

null

msg91_sender_idstring | null

Show child attributes

Any of

string

null

msg91_flow_idstring | null

Show child attributes

Any of

string

null

msg91_routestring144

NotificationService_MSG91ConfigResponse

object

msg91_api_keystring | null••••••••

Show child attributes

Any of

string

null

msg91_sender_idstring | null

Show child attributes

Any of

string

null

msg91_flow_idstring | null

Show child attributes

Any of

string

null

msg91_routestring | null

Show child attributes

Any of

string

null

NotificationService_NotificationSettingsRequest

object

smtpNotificationService_SMTPConfig | null

Show child attributes

Any of

smtp_hoststring | null

Show child attributes

Any of

string

null

smtp_portinteger | null587

Show child attributes

Any of

integer[1, 65535]

null

smtp_usernamestring | null

Show child attributes

Any of

string

null

smtp_passwordstring | null

Show child attributes

Any of

string

null

smtp_from_emailstring | null

Show child attributes

Any of

string

null

smtp_from_namestring | null

Show child attributes

Any of

string

null

smtp_use_tlsbooleantrue

null

sms_providerstringmockaws_end_user_messagingtwiliomsg91kaleyraafricas_talkinggeneric_httpmock

awsNotificationService_AWSConfig | null

Show child attributes

Any of

aws_regionstring | null

Show child attributes

Any of

string

null

aws_access_key_idstring | null

Show child attributes

Any of

string

null

aws_secret_access_keystring | null

Show child attributes

Any of

string

null

aws_origination_numberstring | null

Show child attributes

Any of

string

null

twilioNotificationService_TwilioConfig | null

Show child attributes

Any of

twilio_account_sidstring | null

Show child attributes

Any of

string

null

twilio_auth_tokenstring | null

Show child attributes

Any of

string

null

twilio_from_numberstring | null

Show child attributes

Any of

string

null

msg91NotificationService_MSG91Config | null

Show child attributes

Any of

msg91_api_keystring | null

Show child attributes

Any of

string

null

msg91_sender_idstring | null

Show child attributes

Any of

string

null

msg91_flow_idstring | null

Show child attributes

Any of

string

null

msg91_routestring144

null

kaleyraNotificationService_KaleyraConfig | null

Show child attributes

Any of

kaleyra_api_keystring | null

Show child attributes

Any of

string

null

kaleyra_account_sidstring | null

Show child attributes

Any of

string

null

kaleyra_sender_idstring | null

Show child attributes

Any of

string

null

africas_talkingNotificationService_AfricasTalkingConfig | null

Show child attributes

Any of

africas_talking_usernamestring | null

Show child attributes

Any of

string

null

africas_talking_api_keystring | null

Show child attributes

Any of

string

null

africas_talking_shortcodestring | null

Show child attributes

Any of

string

null

generic_httpNotificationService_GenericHttpConfig | null

Show child attributes

Any of

generic_sms_endpointstring | null

Show child attributes

Any of

string

null

generic_sms_methodstringPOSTGETPOST

generic_sms_auth_header_namestring | null

Show child attributes

Any of

string

null

generic_sms_auth_header_valuestring | null

Show child attributes

Any of

string

null

generic_sms_body_templatestring | null

Show child attributes

Any of

string

null

slackNotificationService_SlackConfig | null

Show child attributes

Any of

slack_webhook_urlstring | null

Show child attributes

Any of

string

null

Example

{
  "smtp": {
    "smtp_host": "string",
    "smtp_port": 587,
    "smtp_username": "string",
    "smtp_password": "string",
    "smtp_from_email": "string",
    "smtp_from_name": "string",
    "smtp_use_tls": true
  },
  "sms_provider": "mock",
  "aws": {
    "aws_region": "string",
    "aws_access_key_id": "string",
    "aws_secret_access_key": "string",
    "aws_origination_number": "string"
  },
  "twilio": {
    "twilio_account_sid": "string",
    "twilio_auth_token": "string",
    "twilio_from_number": "string"
  },
  "msg91": {
    "msg91_api_key": "string",
    "msg91_sender_id": "string",
    "msg91_flow_id": "string",
    "msg91_route": "4"
  },
  "kaleyra": {
    "kaleyra_api_key": "string",
    "kaleyra_account_sid": "string",
    "kaleyra_sender_id": "string"
  },
  "africas_talking": {
    "africas_talking_username": "string",
    "africas_talking_api_key": "string",
    "africas_talking_shortcode": "string"
  },
  "generic_http": {
    "generic_sms_endpoint": "string",
    "generic_sms_method": "POST",
    "generic_sms_auth_header_name": "string",
    "generic_sms_auth_header_value": "string",
    "generic_sms_body_template": "string"
  },
  "slack": {
    "slack_webhook_url": "string"
  }
}

NotificationService_NotificationSettingsResponse

object

sms_providerstringrequired

smtpNotificationService_SMTPConfigResponserequired

Show child attributes

smtp_hoststring | null

Show child attributes

Any of

string

null

smtp_portinteger | null

Show child attributes

Any of

integer

null

smtp_usernamestring | null

Show child attributes

Any of

string

null

smtp_passwordstring | null••••••••

Show child attributes

Any of

string

null

smtp_from_emailstring | null

Show child attributes

Any of

string

null

smtp_from_namestring | null

Show child attributes

Any of

string

null

smtp_use_tlsboolean | null

Show child attributes

Any of

boolean

null

awsNotificationService_AWSConfigResponse | null

Show child attributes

Any of

aws_regionstring | null

Show child attributes

Any of

string

null

aws_access_key_idstring | null••••••••

Show child attributes

Any of

string

null

aws_secret_access_keystring | null••••••••

Show child attributes

Any of

string

null

aws_origination_numberstring | null

Show child attributes

Any of

string

null

twilioNotificationService_TwilioConfigResponse | null

Show child attributes

Any of

twilio_account_sidstring | null

Show child attributes

Any of

string

null

twilio_auth_tokenstring | null••••••••

Show child attributes

Any of

string

null

twilio_from_numberstring | null

Show child attributes

Any of

string

null

msg91NotificationService_MSG91ConfigResponse | null

Show child attributes

Any of

msg91_api_keystring | null••••••••

Show child attributes

Any of

string

null

msg91_sender_idstring | null

Show child attributes

Any of

string

null

msg91_flow_idstring | null

Show child attributes

Any of

string

null

msg91_routestring | null

Show child attributes

Any of

string

null

kaleyraNotificationService_KaleyraConfigResponse | null

Show child attributes

Any of

kaleyra_api_keystring | null••••••••

Show child attributes

Any of

string

null

kaleyra_account_sidstring | null

Show child attributes

Any of

string

null

kaleyra_sender_idstring | null

Show child attributes

Any of

string

null

africas_talkingNotificationService_AfricasTalkingConfigResponse | null

Show child attributes

Any of

africas_talking_usernamestring | null

Show child attributes

Any of

string

null

africas_talking_api_keystring | null••••••••

Show child attributes

Any of

string

null

africas_talking_shortcodestring | null

Show child attributes

Any of

string

null

generic_httpNotificationService_GenericHttpConfigResponse | null

Show child attributes

Any of

generic_sms_endpointstring | null

Show child attributes

Any of

string

null

generic_sms_methodstring | null

Show child attributes

Any of

string

null

generic_sms_auth_header_namestring | null

Show child attributes

Any of

string

null

generic_sms_auth_header_valuestring | null••••••••

Show child attributes

Any of

string

null

generic_sms_body_templatestring | null

Show child attributes

Any of

string

null

slackNotificationService_SlackConfigResponse | null

Show child attributes

Any of

slack_webhook_urlstring | null••••••••

Show child attributes

Any of

string

null

is_activebooleanrequired

created_atstringrequired

updated_atstringrequired

Example

{
  "sms_provider": "string",
  "smtp": {
    "smtp_host": "string",
    "smtp_port": 0,
    "smtp_username": "string",
    "smtp_password": "••••••••",
    "smtp_from_email": "string",
    "smtp_from_name": "string",
    "smtp_use_tls": true
  },
  "aws": {
    "aws_region": "string",
    "aws_access_key_id": "••••••••",
    "aws_secret_access_key": "••••••••",
    "aws_origination_number": "string"
  },
  "twilio": {
    "twilio_account_sid": "string",
    "twilio_auth_token": "••••••••",
    "twilio_from_number": "string"
  },
  "msg91": {
    "msg91_api_key": "••••••••",
    "msg91_sender_id": "string",
    "msg91_flow_id": "string",
    "msg91_route": "string"
  },
  "kaleyra": {
    "kaleyra_api_key": "••••••••",
    "kaleyra_account_sid": "string",
    "kaleyra_sender_id": "string"
  },
  "africas_talking": {
    "africas_talking_username": "string",
    "africas_talking_api_key": "••••••••",
    "africas_talking_shortcode": "string"
  },
  "generic_http": {
    "generic_sms_endpoint": "string",
    "generic_sms_method": "string",
    "generic_sms_auth_header_name": "string",
    "generic_sms_auth_header_value": "••••••••",
    "generic_sms_body_template": "string"
  },
  "slack": {
    "slack_webhook_url": "••••••••"
  },
  "is_active": true,
  "created_at": "string",
  "updated_at": "string"
}

NotificationService_NotificationType

string

NotificationService_SMTPConfig

object

smtp_hoststring | null

Show child attributes

Any of

string

null

smtp_portinteger | null587

Show child attributes

Any of

integer[1, 65535]

null

smtp_usernamestring | null

Show child attributes

Any of

string

null

smtp_passwordstring | null

Show child attributes

Any of

string

null

smtp_from_emailstring | null

Show child attributes

Any of

string

null

smtp_from_namestring | null

Show child attributes

Any of

string

null

smtp_use_tlsbooleantrue

Example

{
  "smtp_host": "string",
  "smtp_port": 587,
  "smtp_username": "string",
  "smtp_password": "string",
  "smtp_from_email": "string",
  "smtp_from_name": "string",
  "smtp_use_tls": true
}

NotificationService_SMTPConfigResponse

object

smtp_hoststring | null

Show child attributes

Any of

string

null

smtp_portinteger | null

Show child attributes

Any of

integer

null

smtp_usernamestring | null

Show child attributes

Any of

string

null

smtp_passwordstring | null••••••••

Show child attributes

Any of

string

null

smtp_from_emailstring | null

Show child attributes

Any of

string

null

smtp_from_namestring | null

Show child attributes

Any of

string

null

smtp_use_tlsboolean | null

Show child attributes

Any of

boolean

null

Example

{
  "smtp_host": "string",
  "smtp_port": 0,
  "smtp_username": "string",
  "smtp_password": "••••••••",
  "smtp_from_email": "string",
  "smtp_from_name": "string",
  "smtp_use_tls": true
}

NotificationService_SendBatchRequest

object

notificationsArray<NotificationService_SendNotificationRequest>required

Show child attributes

channelstringemailsmsslackrequired

recipientstringrequired

subjectstring | null

Show child attributes

Any of

string

null

bodystringrequired

template_idstring | null

Show child attributes

Any of

string

null

template_varsobject | null

Show child attributes

Any of

object

null

user_idstring | null

Show child attributes

Any of

string

null

notification_typeNotificationService_NotificationType | string | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

Example

{
  "notifications": [
    {
      "channel": "email",
      "recipient": "string",
      "subject": "string",
      "body": "string",
      "template_id": "string",
      "template_vars": {},
      "user_id": "string",
      "notification_type": "account_activation",
      "metadata": {}
    }
  ]
}

NotificationService_SendNotificationRequest

object

channelstringemailsmsslackrequired

recipientstringrequired

subjectstring | null

Show child attributes

Any of

string

null

bodystringrequired

template_idstring | null

Show child attributes

Any of

string

null

template_varsobject | null

Show child attributes

Any of

object

null

user_idstring | null

Show child attributes

Any of

string

null

notification_typeNotificationService_NotificationType | string | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

Example

{
  "channel": "email",
  "recipient": "string",
  "subject": "string",
  "body": "string",
  "template_id": "string",
  "template_vars": {},
  "user_id": "string",
  "notification_type": "account_activation",
  "metadata": {}
}

NotificationService_SlackConfig

object

slack_webhook_urlstring | null

Show child attributes

Any of

string

null

NotificationService_SlackConfigResponse

object

slack_webhook_urlstring | null••••••••

Show child attributes

Any of

string

null

NotificationService_TemplateCreateRequest

object

namestringrequired

channelstringrequired

subject_templatestring | null

Show child attributes

Any of

string

null

body_templatestringrequired

variablesArray<string> | null

Show child attributes

Any of

Array<string>

null

NotificationService_TemplateLivePreviewRequest

object

subject_templatestring | null

Show child attributes

Any of

string

null

body_templatestringrequired

variablesobject[object Object]

Show child attributes

[key: string]string

NotificationService_TemplatePreviewRequest

object

variablesobject[object Object]

Show child attributes

[key: string]string

NotificationService_TemplateUpdateRequest

object

namestring | null

Show child attributes

Any of

string

null

subject_templatestring | null

Show child attributes

Any of

string

null

body_templatestring | null

Show child attributes

Any of

string

null

variablesArray<string> | null

Show child attributes

Any of

Array<string>

null

is_activeboolean | null

Show child attributes

Any of

boolean

null

NotificationService_TestNotificationRequest

object

channelstringemailsmsslackrequired

recipientstringrequired

subjectstring | nullTest Notification

Show child attributes

Any of

string

null

bodystringThis is a test notification from MQUAD Notification Service.

NotificationService_TwilioConfig

object

twilio_account_sidstring | null

Show child attributes

Any of

string

null

twilio_auth_tokenstring | null

Show child attributes

Any of

string

null

twilio_from_numberstring | null

Show child attributes

Any of

string

null

NotificationService_TwilioConfigResponse

object

twilio_account_sidstring | null

Show child attributes

Any of

string

null

twilio_auth_tokenstring | null••••••••

Show child attributes

Any of

string

null

twilio_from_numberstring | null

Show child attributes

Any of

string

null

NotificationService_UserPreferenceRequest

object

channelstringrequired

is_enabledbooleantrue

quiet_hours_startstring | null

Show child attributes

Any of

string

null

quiet_hours_endstring | null

Show child attributes

Any of

string

null

frequencystringimmediate

NotificationService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

AuditService_AuditLogCreateRequest

object

event_idstring | null

Unique event ID for idempotency

Show child attributes

Any of

string

null

event_typestring | null

Type of event (e.g., user.created)

Show child attributes

Any of

string

null

log_schema_versionstring | null1.0

Schema version

Show child attributes

Any of

string

null

service_namestringrequired

Name of the service producing the event

actionstringrequired

Action performed (create, update, delete, read, login, etc.)

actor_typestring | null

Type of actor

Show child attributes

Any of

stringuseradminsysteminterviewersupervisor

null

actor_idstring | null

ID of the actor

Show child attributes

Any of

string

null

actor_emailstring | null

Email of the actor

Show child attributes

Any of

string

null

actor_namestring | null

Display name of the actor

Show child attributes

Any of

string

null

tenant_idstring | null

Tenant ID

Show child attributes

Any of

string

null

tenant_namestring | null

Display name of the tenant

Show child attributes

Any of

string

null

resource_typestring | null

Type of resource

Show child attributes

Any of

string

null

resource_idstring | null

ID of the resource

Show child attributes

Any of

string

null

resource_namestring | null

Display name of the resource

Show child attributes

Any of

string

null

statusstring | nullsuccess

Event status

Show child attributes

Any of

stringsuccessfailureerror

null

categorystring | null

Event category for filtering

Show child attributes

Any of

stringAUTHENTICATIONUSER_MANAGEMENTROLE_ACCESSSURVEY_LIFECYCLERESPONSE_DATAINTERVIEWCONSENTEXPORTINTEGRATIONSYNCMEDIACONFIGURATIONSECURITYSYSTEMREVIEWNOTIFICATIONCOMPLIANCE

null

severitystring | nullINFO

Event severity level

Show child attributes

Any of

stringINFOWARNINGCRITICAL

null

descriptionstring | null

Human-readable event description

Show child attributes

Any of

string

null

failure_reasonstring | null

Reason for failure if status is failure/error

Show child attributes

Any of

string

null

correlation_idstring | null

Cross-service correlation ID

Show child attributes

Any of

string

null

ip_addressstring | null

Client IP address

Show child attributes

Any of

string

null

user_agentstring | null

Client user agent

Show child attributes

Any of

string

null

request_idstring | null

Request ID for correlation

Show child attributes

Any of

string

null

trace_idstring | null

Trace ID for cross-service correlation

Show child attributes

Any of

string

null

parent_trace_idstring | null

Parent trace ID

Show child attributes

Any of

string

null

http_methodstring | null

HTTP method

Show child attributes

Any of

string

null

http_pathstring | null

HTTP path

Show child attributes

Any of

string

null

http_statusinteger | null

HTTP status code

Show child attributes

Any of

integer

null

duration_msinteger | null

Request duration in milliseconds

Show child attributes

Any of

integer

null

metadataobject | null

Additional event metadata

Show child attributes

Any of

object

null

event_idempotency_keystring | null

Key for deduplication

Show child attributes

Any of

string

null

data_classificationstring | nullinternal

Data classification level

Show child attributes

Any of

stringpublicinternalsensitiverestricted

null

Example

{
  "action": "create",
  "actor_email": "admin@acme.org",
  "actor_id": "550e8400-e29b-41d4-a716-446655440001",
  "actor_type": "admin",
  "data_classification": "internal",
  "duration_ms": 45,
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "user.created",
  "http_method": "POST",
  "http_path": "/api/v1/users",
  "http_status": 201,
  "ip_address": "192.168.1.1",
  "log_schema_version": "1.0",
  "metadata": {
    "role": "viewer"
  },
  "request_id": "req-12345678",
  "resource_id": "550e8400-e29b-41d4-a716-446655440003",
  "resource_type": "User",
  "service_name": "backend",
  "status": "success",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440002",
  "trace_id": "trace-12345678"
}

Example

{
  "action": "create",
  "actor_email": "admin@acme.org",
  "actor_id": "550e8400-e29b-41d4-a716-446655440001",
  "actor_type": "admin",
  "data_classification": "internal",
  "duration_ms": 45,
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "user.created",
  "http_method": "POST",
  "http_path": "/api/v1/users",
  "http_status": 201,
  "ip_address": "192.168.1.1",
  "log_schema_version": "1.0",
  "metadata": {
    "role": "viewer"
  },
  "request_id": "req-12345678",
  "resource_id": "550e8400-e29b-41d4-a716-446655440003",
  "resource_type": "User",
  "service_name": "backend",
  "status": "success",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440002",
  "trace_id": "trace-12345678"
}

AuditService_AuditLogListResponse

object

itemsArray<AuditService_AuditLogResponse>required

Show child attributes

idstringrequired

event_idstring | null

Show child attributes

Any of

string

null

event_typestring | null

Show child attributes

Any of

string

null

log_schema_versionstring | null

Show child attributes

Any of

string

null

service_namestringrequired

actionstringrequired

actor_typestring | null

Show child attributes

Any of

string

null

actor_idstring | null

Show child attributes

Any of

string

null

actor_emailstring | null

Show child attributes

Any of

string

null

actor_namestring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

tenant_namestring | null

Show child attributes

Any of

string

null

resource_typestring | null

Show child attributes

Any of

string

null

resource_idstring | null

Show child attributes

Any of

string

null

resource_namestring | null

Show child attributes

Any of

string

null

statusstring | null

Show child attributes

Any of

string

null

categorystring | null

Show child attributes

Any of

string

null

severitystring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

failure_reasonstring | null

Show child attributes

Any of

string

null

correlation_idstring | null

Show child attributes

Any of

string

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

request_idstring | null

Show child attributes

Any of

string

null

trace_idstring | null

Show child attributes

Any of

string

null

parent_trace_idstring | null

Show child attributes

Any of

string

null

http_methodstring | null

Show child attributes

Any of

string

null

http_pathstring | null

Show child attributes

Any of

string

null

http_statusinteger | null

Show child attributes

Any of

integer

null

duration_msinteger | null

Show child attributes

Any of

integer

null

metadataobject | null

Show child attributes

Any of

object

null

data_classificationstring | null

Show child attributes

Any of

string

null

checksumstringrequired

created_atstringrequired

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "event_id": "string",
      "event_type": "string",
      "log_schema_version": "string",
      "service_name": "string",
      "action": "string",
      "actor_type": "string",
      "actor_id": "string",
      "actor_email": "string",
      "actor_name": "string",
      "tenant_id": "string",
      "tenant_name": "string",
      "resource_type": "string",
      "resource_id": "string",
      "resource_name": "string",
      "status": "string",
      "category": "string",
      "severity": "string",
      "description": "string",
      "failure_reason": "string",
      "correlation_id": "string",
      "ip_address": "string",
      "user_agent": "string",
      "request_id": "string",
      "trace_id": "string",
      "parent_trace_id": "string",
      "http_method": "string",
      "http_path": "string",
      "http_status": 0,
      "duration_ms": 0,
      "metadata": {},
      "data_classification": "string",
      "checksum": "string",
      "created_at": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

AuditService_AuditLogResponse

object

idstringrequired

event_idstring | null

Show child attributes

Any of

string

null

event_typestring | null

Show child attributes

Any of

string

null

log_schema_versionstring | null

Show child attributes

Any of

string

null

service_namestringrequired

actionstringrequired

actor_typestring | null

Show child attributes

Any of

string

null

actor_idstring | null

Show child attributes

Any of

string

null

actor_emailstring | null

Show child attributes

Any of

string

null

actor_namestring | null

Show child attributes

Any of

string

null

tenant_idstring | null

Show child attributes

Any of

string

null

tenant_namestring | null

Show child attributes

Any of

string

null

resource_typestring | null

Show child attributes

Any of

string

null

resource_idstring | null

Show child attributes

Any of

string

null

resource_namestring | null

Show child attributes

Any of

string

null

statusstring | null

Show child attributes

Any of

string

null

categorystring | null

Show child attributes

Any of

string

null

severitystring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

failure_reasonstring | null

Show child attributes

Any of

string

null

correlation_idstring | null

Show child attributes

Any of

string

null

ip_addressstring | null

Show child attributes

Any of

string

null

user_agentstring | null

Show child attributes

Any of

string

null

request_idstring | null

Show child attributes

Any of

string

null

trace_idstring | null

Show child attributes

Any of

string

null

parent_trace_idstring | null

Show child attributes

Any of

string

null

http_methodstring | null

Show child attributes

Any of

string

null

http_pathstring | null

Show child attributes

Any of

string

null

http_statusinteger | null

Show child attributes

Any of

integer

null

duration_msinteger | null

Show child attributes

Any of

integer

null

metadataobject | null

Show child attributes

Any of

object

null

data_classificationstring | null

Show child attributes

Any of

string

null

checksumstringrequired

created_atstringrequired

Example

{
  "id": "string",
  "event_id": "string",
  "event_type": "string",
  "log_schema_version": "string",
  "service_name": "string",
  "action": "string",
  "actor_type": "string",
  "actor_id": "string",
  "actor_email": "string",
  "actor_name": "string",
  "tenant_id": "string",
  "tenant_name": "string",
  "resource_type": "string",
  "resource_id": "string",
  "resource_name": "string",
  "status": "string",
  "category": "string",
  "severity": "string",
  "description": "string",
  "failure_reason": "string",
  "correlation_id": "string",
  "ip_address": "string",
  "user_agent": "string",
  "request_id": "string",
  "trace_id": "string",
  "parent_trace_id": "string",
  "http_method": "string",
  "http_path": "string",
  "http_status": 0,
  "duration_ms": 0,
  "metadata": {},
  "data_classification": "string",
  "checksum": "string",
  "created_at": "string"
}

AuditService_ConsentRecordRequest

object

user_idstringrequired

consent_typestringrequired

is_grantedbooleanrequired

ip_addressstring | null

Show child attributes

Any of

string

null

metadataobject | null

Show child attributes

Any of

object

null

AuditService_ConsentRecordResponse

object

idstringrequired

user_idstringrequired

consent_typestringrequired

is_grantedbooleanrequired

granted_atstring | null

Show child attributes

Any of

string

null

revoked_atstring | null

Show child attributes

Any of

string

null

created_atstringrequired

AuditService_HTTPValidationError

object

detailArray<AuditService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

AuditService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

FeatureFlagsService_BatchEvaluateRequest

object

flagsArray<FeatureFlagsService_EvaluateRequest>required

Show child attributes

flag_keystringrequired

contextobject | null

Show child attributes

Any of

object

null

FeatureFlagsService_BatchEvaluateResponse

object

resultsArray<FeatureFlagsService_EvaluateResponse>required

Show child attributes

flag_keystringrequired

valueanyrequired

is_enabledbooleanrequired

matched_rulestring | null

Show child attributes

Any of

string

null

FeatureFlagsService_EntitlementCatalogueItem

object

keystringrequired

source_keystringrequired

namestringrequired

typestringrequired

unitstring | null

Show child attributes

Any of

string

null

categorystringrequired

scopestringtenant

reset_periodstring | null

Show child attributes

Any of

string

null

counting_rulestringrequired

ui_labelstringrequired

upgrade_messagestringrequired

error_codestringrequired

override_allowedbooleantrue

stale_acceptablebooleanfalse

requires_role_permissionbooleantrue

downgrade_policystringrequired

applicable_servicesArray<string>required

Example

{
  "key": "string",
  "source_key": "string",
  "name": "string",
  "type": "string",
  "unit": "string",
  "category": "string",
  "scope": "tenant",
  "reset_period": "string",
  "counting_rule": "string",
  "ui_label": "string",
  "upgrade_message": "string",
  "error_code": "string",
  "override_allowed": true,
  "stale_acceptable": false,
  "requires_role_permission": true,
  "downgrade_policy": "string",
  "applicable_services": [
    "string"
  ]
}

FeatureFlagsService_EntitlementCatalogueResponse

object

itemsArray<FeatureFlagsService_EntitlementCatalogueItem>required

Show child attributes

keystringrequired

source_keystringrequired

namestringrequired

typestringrequired

unitstring | null

Show child attributes

Any of

string

null

categorystringrequired

scopestringtenant

reset_periodstring | null

Show child attributes

Any of

string

null

counting_rulestringrequired

ui_labelstringrequired

upgrade_messagestringrequired

error_codestringrequired

override_allowedbooleantrue

stale_acceptablebooleanfalse

requires_role_permissionbooleantrue

downgrade_policystringrequired

applicable_servicesArray<string>required

Example

{
  "items": [
    {
      "key": "string",
      "source_key": "string",
      "name": "string",
      "type": "string",
      "unit": "string",
      "category": "string",
      "scope": "tenant",
      "reset_period": "string",
      "counting_rule": "string",
      "ui_label": "string",
      "upgrade_message": "string",
      "error_code": "string",
      "override_allowed": true,
      "stale_acceptable": false,
      "requires_role_permission": true,
      "downgrade_policy": "string",
      "applicable_services": [
        "string"
      ]
    }
  ]
}

FeatureFlagsService_EvaluateRequest

object

flag_keystringrequired

contextobject | null

Show child attributes

Any of

object

null

FeatureFlagsService_EvaluateResponse

object

flag_keystringrequired

valueanyrequired

is_enabledbooleanrequired

matched_rulestring | null

Show child attributes

Any of

string

null

FeatureFlagsService_FlagCreateRequest

object

keystringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

flag_typestringboolean

default_valueanyfalse

is_enabledbooleantrue

tagsArray<string> | null

Show child attributes

Any of

Array<string>

null

environmentstring | null

Show child attributes

Any of

string

null

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

Example

{
  "key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "boolean",
  "default_value": false,
  "is_enabled": true,
  "tags": [
    "string"
  ],
  "environment": "string",
  "plan_tier": "string",
  "feature_category": "string"
}

FeatureFlagsService_FlagListResponse

object

itemsArray<FeatureFlagsService_FlagResponse>required

Show child attributes

idstringrequired

keystringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

flag_typestringrequired

default_valueanyrequired

is_enabledbooleanrequired

is_archivedbooleanrequired

tagsArray<string>required

evaluation_countintegerrequired

last_evaluated_atstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

totalintegerrequired

skipintegerrequired

limitintegerrequired

has_nextbooleanrequired

has_previousbooleanrequired

Example

{
  "items": [
    {
      "id": "string",
      "key": "string",
      "name": "string",
      "description": "string",
      "flag_type": "string",
      "is_enabled": true,
      "is_archived": true,
      "tags": [
        "string"
      ],
      "evaluation_count": 0,
      "last_evaluated_at": "string",
      "created_at": "string",
      "updated_at": "string",
      "plan_tier": "string",
      "feature_category": "string"
    }
  ],
  "total": 0,
  "skip": 0,
  "limit": 0,
  "has_next": true,
  "has_previous": true
}

FeatureFlagsService_FlagResponse

object

idstringrequired

keystringrequired

namestringrequired

descriptionstring | null

Show child attributes

Any of

string

null

flag_typestringrequired

default_valueanyrequired

is_enabledbooleanrequired

is_archivedbooleanrequired

tagsArray<string>required

evaluation_countintegerrequired

last_evaluated_atstring | null

Show child attributes

Any of

string

null

created_atstringrequired

updated_atstringrequired

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

Example

{
  "id": "string",
  "key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "string",
  "is_enabled": true,
  "is_archived": true,
  "tags": [
    "string"
  ],
  "evaluation_count": 0,
  "last_evaluated_at": "string",
  "created_at": "string",
  "updated_at": "string",
  "plan_tier": "string",
  "feature_category": "string"
}

FeatureFlagsService_FlagUpdateRequest

object

namestring | null

Show child attributes

Any of

string

null

descriptionstring | null

Show child attributes

Any of

string

null

default_valueany | null

Show child attributes

Any of

any

null

is_enabledboolean | null

Show child attributes

Any of

boolean

null

tagsArray<string> | null

Show child attributes

Any of

Array<string>

null

plan_tierstring | null

Show child attributes

Any of

string

null

feature_categorystring | null

Show child attributes

Any of

string

null

FeatureFlagsService_HTTPValidationError

object

detailArray<FeatureFlagsService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

FeatureFlagsService_HealthResponseDTO

object

Health check response model.

statusstringrequired

servicestringrequired

versionstringrequired

timestampstring<date-time>required

FeatureFlagsService_InvalidateResponse

object

tenant_idstringrequired

invalidatedbooleanrequired

messagestringrequired

FeatureFlagsService_LimitItem

object

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

valueintegerrequired

categorystringresource

scopestringtenant

reset_periodstring | null

Show child attributes

Any of

string

null

unlimitedbooleanfalse

custom_overridebooleanfalse

Example

{
  "key": "string",
  "canonical_key": "string",
  "name": "string",
  "value": 0,
  "category": "resource",
  "scope": "tenant",
  "reset_period": "string",
  "unlimited": false,
  "custom_override": false
}

FeatureFlagsService_PlanDto

object

idstringrequired

namestringrequired

descriptionstringrequired

price_idstringrequired

amountnumberrequired

currencystringrequired

intervalstringrequired

featuresArray<FeatureFlagsService_PlanFeatureDto>required

Show child attributes

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

descriptionstringrequired

flag_typestringrequired

valueboolean | integer | stringrequired

Show child attributes

Any of

boolean

integer

string

categorystringrequired

unitstring | null

Show child attributes

Any of

string

null

ui_labelstring | null

Show child attributes

Any of

string

null

upgrade_messagestring | null

Show child attributes

Any of

string

null

error_codestring | null

Show child attributes

Any of

string

null

override_allowedbooleantrue

limitsArray<FeatureFlagsService_PlanLimitDto>

Show child attributes

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

valueintegerrequired

categorystringrequired

scopestringrequired

reset_periodstring | null

Show child attributes

Any of

string

null

unlimitedbooleanfalse

custom_overridebooleanfalse

unitstring | null

Show child attributes

Any of

string

null

ui_labelstring | null

Show child attributes

Any of

string

null

counting_rulestring | null

Show child attributes

Any of

string

null

upgrade_messagestring | null

Show child attributes

Any of

string

null

error_codestring | null

Show child attributes

Any of

string

null

override_allowedbooleantrue

Example

{
  "id": "string",
  "name": "string",
  "description": "string",
  "price_id": "string",
  "amount": 0,
  "currency": "string",
  "interval": "string",
  "features": [
    {
      "key": "string",
      "canonical_key": "string",
      "name": "string",
      "description": "string",
      "flag_type": "string",
      "value": true,
      "category": "string",
      "unit": "string",
      "ui_label": "string",
      "upgrade_message": "string",
      "error_code": "string",
      "override_allowed": true
    }
  ],
  "limits": [
    {
      "key": "string",
      "canonical_key": "string",
      "name": "string",
      "value": 0,
      "category": "string",
      "scope": "string",
      "reset_period": "string",
      "unlimited": false,
      "custom_override": false,
      "unit": "string",
      "ui_label": "string",
      "counting_rule": "string",
      "upgrade_message": "string",
      "error_code": "string",
      "override_allowed": true
    }
  ]
}

FeatureFlagsService_PlanFeatureDto

object

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

descriptionstringrequired

flag_typestringrequired

valueboolean | integer | stringrequired

Show child attributes

Any of

boolean

integer

string

categorystringrequired

unitstring | null

Show child attributes

Any of

string

null

ui_labelstring | null

Show child attributes

Any of

string

null

upgrade_messagestring | null

Show child attributes

Any of

string

null

error_codestring | null

Show child attributes

Any of

string

null

override_allowedbooleantrue

Example

{
  "key": "string",
  "canonical_key": "string",
  "name": "string",
  "description": "string",
  "flag_type": "string",
  "value": true,
  "category": "string",
  "unit": "string",
  "ui_label": "string",
  "upgrade_message": "string",
  "error_code": "string",
  "override_allowed": true
}

FeatureFlagsService_PlanLimitDto

object

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

valueintegerrequired

categorystringrequired

scopestringrequired

reset_periodstring | null

Show child attributes

Any of

string

null

unlimitedbooleanfalse

custom_overridebooleanfalse

unitstring | null

Show child attributes

Any of

string

null

ui_labelstring | null

Show child attributes

Any of

string

null

counting_rulestring | null

Show child attributes

Any of

string

null

upgrade_messagestring | null

Show child attributes

Any of

string

null

error_codestring | null

Show child attributes

Any of

string

null

override_allowedbooleantrue

Example

{
  "key": "string",
  "canonical_key": "string",
  "name": "string",
  "value": 0,
  "category": "string",
  "scope": "string",
  "reset_period": "string",
  "unlimited": false,
  "custom_override": false,
  "unit": "string",
  "ui_label": "string",
  "counting_rule": "string",
  "upgrade_message": "string",
  "error_code": "string",
  "override_allowed": true
}

FeatureFlagsService_PlanListResponse

object

itemsArray<FeatureFlagsService_PlanDto>required

Show child attributes

idstringrequired

namestringrequired

descriptionstringrequired

price_idstringrequired

amountnumberrequired

currencystringrequired

intervalstringrequired

featuresArray<FeatureFlagsService_PlanFeatureDto>required

Show child attributes

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

descriptionstringrequired

flag_typestringrequired

valueboolean | integer | stringrequired

Show child attributes

Any of

boolean

integer

string

categorystringrequired

unitstring | null

Show child attributes

Any of

string

null

ui_labelstring | null

Show child attributes

Any of

string

null

upgrade_messagestring | null

Show child attributes

Any of

string

null

error_codestring | null

Show child attributes

Any of

string

null

override_allowedbooleantrue

limitsArray<FeatureFlagsService_PlanLimitDto>

Show child attributes

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

valueintegerrequired

categorystringrequired

scopestringrequired

reset_periodstring | null

Show child attributes

Any of

string

null

unlimitedbooleanfalse

custom_overridebooleanfalse

unitstring | null

Show child attributes

Any of

string

null

ui_labelstring | null

Show child attributes

Any of

string

null

counting_rulestring | null

Show child attributes

Any of

string

null

upgrade_messagestring | null

Show child attributes

Any of

string

null

error_codestring | null

Show child attributes

Any of

string

null

override_allowedbooleantrue

Example

{
  "items": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "price_id": "string",
      "amount": 0,
      "currency": "string",
      "interval": "string",
      "features": [
        {
          "key": "string",
          "canonical_key": "string",
          "name": "string",
          "description": "string",
          "flag_type": "string",
          "value": true,
          "category": "string",
          "unit": "string",
          "ui_label": "string",
          "upgrade_message": "string",
          "error_code": "string",
          "override_allowed": true
        }
      ],
      "limits": [
        {
          "key": "string",
          "canonical_key": "string",
          "name": "string",
          "value": 0,
          "category": "string",
          "scope": "string",
          "reset_period": "string",
          "unlimited": false,
          "custom_override": false,
          "unit": "string",
          "ui_label": "string",
          "counting_rule": "string",
          "upgrade_message": "string",
          "error_code": "string",
          "override_allowed": true
        }
      ]
    }
  ]
}

FeatureFlagsService_TenantEntitlementsResponse

object

tenant_idstringrequired

tierstringrequired

subscription_statusstringrequired

activebooleanrequired

trialbooleanrequired

trial_end_atstring | null

Show child attributes

Any of

string

null

dormantbooleanrequired

limitsArray<FeatureFlagsService_LimitItem>required

Show child attributes

keystringrequired

canonical_keystring | null

Show child attributes

Any of

string

null

namestringrequired

valueintegerrequired

categorystringresource

scopestringtenant

reset_periodstring | null

Show child attributes

Any of

string

null

unlimitedbooleanfalse

custom_overridebooleanfalse

featuresArray<object>required

Example

{
  "tenant_id": "string",
  "tier": "string",
  "subscription_status": "string",
  "active": true,
  "trial": true,
  "trial_end_at": "string",
  "dormant": true,
  "limits": [
    {
      "key": "string",
      "canonical_key": "string",
      "name": "string",
      "value": 0,
      "category": "resource",
      "scope": "tenant",
      "reset_period": "string",
      "unlimited": false,
      "custom_override": false
    }
  ],
  "features": [
    {}
  ]
}

FeatureFlagsService_TenantFeaturesResponse

object

itemsArray<object>required

tierstringrequired

FeatureFlagsService_TenantLimitsResponse

object

itemsArray<object>required

tierstringrequired

tenant_idstringrequired

FeatureFlagsService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

QuotaService_CheckLimitRequest

object

Request to check quota availability.

limit_typestringrequired

Type of limit (e.g., 'surveys')

amountinteger>= 11

Amount to check

QuotaService_ConsumeQuotaRequest

object

Request to consume quota.

limit_typestringrequired

Type of limit

amountinteger>= 11

Amount to consume

idempotency_keystring | null

Tenant-scoped usage idempotency key

Show child attributes

Any of

string

null

QuotaService_HTTPValidationError

object

detailArray<QuotaService_ValidationError>

Show child attributes

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject

QuotaService_QuotaResponse

object

Response from quota operations.

successbooleanrequired

allowedbooleanrequired

currentintegerrequired

limitintegerrequired

remainingintegerrequired

reset_atstring | null

Show child attributes

Any of

string<date-time>

null

unlimitedbooleanfalse

QuotaService_RollbackRequest

object

Request to rollback quota.

limit_typestringrequired

Type of limit

amountinteger>= 11

Amount to rollback

QuotaService_ValidationError

object

locArray<string | integer>required

Show child attributes

Any of

string

integer

msgstringrequired

typestringrequired

inputany

ctxobject