Skip to content
TellMeHow Developers
en

API documentation

Interviews

Interviews: 18 API operations, with their parameters, body, responses and a curl example.

GET /engagements/{engagement}/interviews

Read engagements.interviews.index

Parameters

engagement path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/interviews" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/interviews/preview-session

Write engagements.interviews.preview

Parameters

engagement path
Identifier (ULID).

Body application/json

  • population_id string | null

    length: exactly 26

  • mode object

    one of voice_screen voice_only text_simulation

  • locale string | null

    length: at most 8

  • client_info array<object> | null
  • client_info.os string | null

    length: at most 64

  • client_info.browser string | null

    length: at most 64

  • client_info.device_class string | null

    length: at most 64

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/interviews/preview-session" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"population_id":"01JABCDEFGHJKMNPQRSTVWXYZ0","mode":"voice_screen","locale":"…"}'

POST /engagements/{engagement}/interviews/test

Write engagements.interviews.test

Parameters

engagement path
Identifier (ULID).

Body application/json

  • population_id string | null

    length: exactly 26

  • mode object

    one of voice_screen voice_only text_simulation

  • locale string | null

    length: at most 8

  • client_info array<object> | null
  • client_info.os string | null

    length: at most 64

  • client_info.browser string | null

    length: at most 64

  • client_info.device_class string | null

    length: at most 64

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/interviews/test" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"population_id":"01JABCDEFGHJKMNPQRSTVWXYZ0","mode":"voice_screen","locale":"…"}'

GET /engagements/{engagement}/live-sessions

Read engagements.live-sessions

Parameters

engagement path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/live-sessions" \
  -H "Authorization: Bearer pat_…"

GET /interviews/{interview}

Read interviews.show

Parameters

interview path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/interviews/{interview}" \
  -H "Authorization: Bearer pat_…"

GET /interviews/{interview}/chapters

Read interviews.chapters

Parameters

interview path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/interviews/{interview}/chapters" \
  -H "Authorization: Bearer pat_…"

GET /interviews/{interview}/chapters/{chapter}/recap

Read interviews.chapters.recap

Parameters

interview path
Identifier (ULID).
chapter path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/interviews/{interview}/chapters/{chapter}/recap" \
  -H "Authorization: Bearer pat_…"

GET /interviews/{interview}/sources/{type}/{source}

Read interviews.sources.show

Parameters

interview path
Identifier (ULID).
type path
Identifier (ULID).
source path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/interviews/{interview}/sources/{type}/{source}" \
  -H "Authorization: Bearer pat_…"

GET /media-thumbnails/{disk}/{path}

Read interviews.media.thumbnail

Parameters

disk path
Value from a fixed list (type, language, level…).
path path
Value from a fixed list (type, language, level…).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/media-thumbnails/{disk}/{path}" \
  -H "Authorization: Bearer pat_…"

GET /media/{disk}/{path}

Read interviews.media

Parameters

disk path
Value from a fixed list (type, language, level…).
path path
Value from a fixed list (type, language, level…).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/media/{disk}/{path}" \
  -H "Authorization: Bearer pat_…"

GET /sessions/{session}

Read sessions.show

Parameters

session path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/sessions/{session}" \
  -H "Authorization: Bearer pat_…"

GET /sessions/{session}/artifacts

Read sessions.artifacts

Parameters

session path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/sessions/{session}/artifacts" \
  -H "Authorization: Bearer pat_…"

POST /sessions/{session}/end

Write sessions.end

Parameters

session path
Identifier (ULID).

Responses

  • 201 Created (200 or 202 for an action or an asynchronous job).
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl -X POST "https://{your-workspace}.tellmehow.io/api/v1/sessions/{session}/end" \
  -H "Authorization: Bearer pat_…"

GET /sessions/{session}/frames

Read sessions.frames

Parameters

session path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/sessions/{session}/frames" \
  -H "Authorization: Bearer pat_…"

GET /sessions/{session}/frames/latest

Read sessions.frames.latest

Parameters

session path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/sessions/{session}/frames/latest" \
  -H "Authorization: Bearer pat_…"

GET /sessions/{session}/pins

Read sessions.pins

Parameters

session path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/sessions/{session}/pins" \
  -H "Authorization: Bearer pat_…"

GET /sessions/{session}/recordings/{recording}/stream

Read sessions.recordings.stream

Parameters

session path
Identifier (ULID).
recording path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/sessions/{session}/recordings/{recording}/stream" \
  -H "Authorization: Bearer pat_…"

GET /sessions/{session}/transcript

Read sessions.transcript

Parameters

session path
Identifier (ULID).
cursor limit query
Cursor pagination, for operations that return a paginated list.

Responses

  • 200 Success: the resource in data.
  • 401 Missing, invalid, revoked or expired token.
  • 403 Not allowed by the role, a rule or the scope.
  • 404 Unknown resource or outside the workspace.
  • 422 Invalid data (validation.failed).
  • 429 Rate limit reached.
Example 
curl "https://{your-workspace}.tellmehow.io/api/v1/sessions/{session}/transcript" \
  -H "Authorization: Bearer pat_…"