Skip to content
TellMeHow Developers
en

API documentation

Analysis

Analysis: 59 API operations, with their parameters, body, responses and a curl example.

GET /analysis/enums/{name}

Read analysis.enums

Parameters

name 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/analysis/enums/{name}" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/analysis/runs

Read engagements.analysis.runs.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}/analysis/runs" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/analysis/runs

Write engagements.analysis.runs.store

Parameters

engagement path
Identifier (ULID).

Body application/json

  • mode object required

    one of incremental full

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}/analysis/runs" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"mode":"incremental"}'

POST /engagements/{engagement}/analysis/runs/{run}/cancel

Write engagements.analysis.runs.cancel

Parameters

engagement path
Identifier (ULID).
run 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/engagements/{engagement}/analysis/runs/{run}/cancel" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/analysis/summary

Read engagements.analysis.summary

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}/analysis/summary" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/change-proposals

Read engagements.analysis.change-proposals.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}/change-proposals" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/change-proposals/accept-all

Write engagements.analysis.change-proposals.accept-all

Parameters

engagement path
Identifier (ULID).

Body application/json

  • entity_type object

    one of process process_step process_flow finding opportunity

  • analysis_run_id string | null

    length: exactly 26

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}/change-proposals/accept-all" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"entity_type":"process","analysis_run_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'

POST /engagements/{engagement}/change-proposals/reject-all

Write engagements.analysis.change-proposals.reject-all

Parameters

engagement path
Identifier (ULID).

Body application/json

  • entity_type object

    one of process process_step process_flow finding opportunity

  • analysis_run_id string | null

    length: exactly 26

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}/change-proposals/reject-all" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"entity_type":"process","analysis_run_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'

POST /engagements/{engagement}/change-proposals/{proposal}/accept

Write engagements.analysis.change-proposals.accept

Parameters

engagement path
Identifier (ULID).
proposal 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/engagements/{engagement}/change-proposals/{proposal}/accept" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/change-proposals/{proposal}/reject

Write engagements.analysis.change-proposals.reject

Parameters

engagement path
Identifier (ULID).
proposal 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/engagements/{engagement}/change-proposals/{proposal}/reject" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/contradictions

Read engagements.analysis.contradictions.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}/contradictions" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/contradictions/{contradiction}/resolve

Write engagements.analysis.contradictions.resolve

Parameters

engagement path
Identifier (ULID).
contradiction path
Identifier (ULID).

Body application/json

  • status string required

    one of resolved kept_as_finding dismissed

  • resolution_note string | null

    length: at most 2000

  • resolved_finding_id string | null

    length: exactly 26

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}/contradictions/{contradiction}/resolve" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"status":"resolved"}'

PATCH /engagements/{engagement}/evidences/{evidence}

Write engagements.analysis.evidences.update

Parameters

engagement path
Identifier (ULID).
evidence path
Identifier (ULID).

Body application/json

  • is_publishable boolean required

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 -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/evidences/{evidence}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"is_publishable":true}'

GET /engagements/{engagement}/evidences/{evidence}/preview

Read engagements.analysis.evidences.preview

Parameters

engagement path
Identifier (ULID).
evidence 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}/evidences/{evidence}/preview" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/findings

Read engagements.analysis.findings.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}/findings" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/findings

Write engagements.analysis.findings.store

Parameters

engagement path
Identifier (ULID).

Body application/json

  • type object required

    one of irritant re_entry volume duration business_rule tool key_person_dependency risk good_practice other

  • statement string required

    length: at most 1000

  • details string | null

    length: at most 4000

  • quantity array<object> | null
  • process_id string | null

    length: exactly 26

  • step_id string | null

    length: exactly 26

  • deliverable_category string | null

    length: at most 64

  • evidences array<object>
  • evidences[].source_type object required

    one of transcript_segment screen_frame pin artifact_chunk external_source_item recap_item

  • evidences[].source_id string required

    length: exactly 26

  • evidences[].locator array<object> | null
  • evidences[].excerpt string | null

    length: at most 1000

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}/findings" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"type":"irritant","statement":"…"}'

GET /engagements/{engagement}/findings/{finding}

Read engagements.analysis.findings.show

Parameters

engagement path
Identifier (ULID).
finding 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}/findings/{finding}" \
  -H "Authorization: Bearer pat_…"

PATCH /engagements/{engagement}/findings/{finding}

Write engagements.analysis.findings.update

Parameters

engagement path
Identifier (ULID).
finding path
Identifier (ULID).

Body application/json

  • type object

    one of irritant re_entry volume duration business_rule tool key_person_dependency risk good_practice other

  • statement string

    length: at most 1000

  • details string | null

    length: at most 4000

  • quantity array<object> | null
  • process_id string | null

    length: exactly 26

  • step_id string | null

    length: exactly 26

  • deliverable_category string | null

    length: at most 64

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 -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/findings/{finding}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"type":"irritant","statement":"…","details":"…"}'

DELETE /engagements/{engagement}/findings/{finding}

Write engagements.analysis.findings.destroy

Parameters

engagement path
Identifier (ULID).
finding path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 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 DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/findings/{finding}" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/findings/{finding}/evidences

Write engagements.analysis.findings.evidences.store

Parameters

engagement path
Identifier (ULID).
finding path
Identifier (ULID).

Body application/json

  • source_type object required

    one of transcript_segment screen_frame pin artifact_chunk external_source_item recap_item

  • source_id string required

    length: exactly 26

  • locator array<object> | null
  • excerpt string | null

    length: at most 1000

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}/findings/{finding}/evidences" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"source_type":"transcript_segment","source_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'

DELETE /engagements/{engagement}/findings/{finding}/evidences/{evidence}

Write engagements.analysis.findings.evidences.destroy

Parameters

engagement path
Identifier (ULID).
finding path
Identifier (ULID).
evidence path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 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 DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/findings/{finding}/evidences/{evidence}" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/findings/{finding}/review

Write engagements.analysis.findings.review

Parameters

engagement path
Identifier (ULID).
finding path
Identifier (ULID).

Body application/json

  • review_status object required

    one of proposed validated rejected

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}/findings/{finding}/review" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"review_status":"proposed"}'

GET /engagements/{engagement}/follow-ups

Read engagements.analysis.follow-ups.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}/follow-ups" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/follow-ups

Write engagements.analysis.follow-ups.store

Parameters

engagement path
Identifier (ULID).

Body application/json

  • reason object required

    one of contradiction gap uncertain_figure shallow_topic gain_data

  • title string required

    length: at most 255

  • questions array<string> required

    items: at least 2 items: at most 5

  • estimated_minutes integer required

    at least 5 at most 15

  • participant_ids array<string> required

    items: at least 1

  • contradiction_id string | null

    length: exactly 26

  • finding_id string | null

    length: exactly 26

  • topic_key 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}/follow-ups" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"reason":"contradiction","title":"…","questions":[],"estimated_minutes":5,"participant_ids":[]}'

PATCH /engagements/{engagement}/follow-ups/{proposal}

Write engagements.analysis.follow-ups.update

Parameters

engagement path
Identifier (ULID).
proposal path
Identifier (ULID).

Body application/json

  • title string

    length: at most 255

  • questions array<string>

    items: at least 2 items: at most 5

  • estimated_minutes integer

    at least 5 at most 15

  • participant_ids array<string>

    items: at least 1

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 -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/follow-ups/{proposal}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"…","questions":[],"estimated_minutes":5}'

POST /engagements/{engagement}/follow-ups/{proposal}/accept

Write engagements.analysis.follow-ups.accept

Parameters

engagement path
Identifier (ULID).
proposal path
Identifier (ULID).

Body application/json

  • send_now boolean | null

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}/follow-ups/{proposal}/accept" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"send_now":true}'

POST /engagements/{engagement}/follow-ups/{proposal}/decline

Write engagements.analysis.follow-ups.decline

Parameters

engagement path
Identifier (ULID).
proposal 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/engagements/{engagement}/follow-ups/{proposal}/decline" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/opportunities

Read engagements.analysis.opportunities.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}/opportunities" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/opportunities

Write engagements.analysis.opportunities.store

Parameters

engagement path
Identifier (ULID).

Body application/json

  • title string required

    length: at most 255

  • problem string required

    length: at most 4000

  • solution string required

    length: at most 4000

  • category string required

    length: at most 64

  • gain array<object> | null
  • effort object required

    one of low medium high

  • priority string | null

    length: at most 32

  • risks string | null

    length: at most 2000

  • finding_ids array<string> required

    items: at least 1

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}/opportunities" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"…","problem":"…","solution":"…","category":"…","effort":"low","finding_ids":[]}'

PATCH /engagements/{engagement}/opportunities/{opportunity}

Write engagements.analysis.opportunities.update

Parameters

engagement path
Identifier (ULID).
opportunity path
Identifier (ULID).

Body application/json

  • title string

    length: at most 255

  • problem string

    length: at most 4000

  • solution string

    length: at most 4000

  • category string

    length: at most 64

  • gain array<object> | null
  • effort object

    one of low medium high

  • priority string | null

    length: at most 32

  • risks string | null

    length: at most 2000

  • finding_ids array<string>

    items: at least 1

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 -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/opportunities/{opportunity}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"title":"…","problem":"…","solution":"…"}'

DELETE /engagements/{engagement}/opportunities/{opportunity}

Write engagements.analysis.opportunities.destroy

Parameters

engagement path
Identifier (ULID).
opportunity path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 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 DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/opportunities/{opportunity}" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/opportunities/{opportunity}/review

Write engagements.analysis.opportunities.review

Parameters

engagement path
Identifier (ULID).
opportunity path
Identifier (ULID).

Body application/json

  • review_status object required

    one of proposed validated rejected

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}/opportunities/{opportunity}/review" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"review_status":"proposed"}'

GET /engagements/{engagement}/processes

Read engagements.analysis.processes.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}/processes" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/processes

Write engagements.analysis.processes.store

Parameters

engagement path
Identifier (ULID).

Body application/json

  • name string required

    length: at most 255

  • description string | null

    length: at most 4000

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}/processes" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

GET /engagements/{engagement}/processes/{process}

Read engagements.analysis.processes.show

Parameters

engagement path
Identifier (ULID).
process 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}/processes/{process}" \
  -H "Authorization: Bearer pat_…"

PATCH /engagements/{engagement}/processes/{process}

Write engagements.analysis.processes.update

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).

Body application/json

  • name string

    length: at most 255

  • description string | null

    length: at most 4000

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 -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/processes/{process}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","description":"…"}'

DELETE /engagements/{engagement}/processes/{process}

Write engagements.analysis.processes.destroy

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 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 DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/processes/{process}" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/processes/{process}/actors

Write engagements.analysis.actors.store

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).

Body application/json

  • role_label string required

    length: at most 255

  • population_id string | null

    length: exactly 26

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}/processes/{process}/actors" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"role_label":"…"}'

PATCH /engagements/{engagement}/processes/{process}/actors/{actor}

Write engagements.analysis.actors.update

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).
actor path
Identifier (ULID).

Body application/json

  • role_label string required

    length: at most 255

  • population_id string | null

    length: exactly 26

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 -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/processes/{process}/actors/{actor}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"role_label":"…"}'

DELETE /engagements/{engagement}/processes/{process}/actors/{actor}

Write engagements.analysis.actors.destroy

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).
actor path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 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 DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/processes/{process}/actors/{actor}" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/processes/{process}/flows

Write engagements.analysis.flows.store

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).

Body application/json

  • from_step_id string required

    length: exactly 26

  • to_step_id string required

    length: exactly 26

  • condition_label string | null

    length: at most 255

  • variant_id string | null

    length: exactly 26

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}/processes/{process}/flows" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"from_step_id":"01JABCDEFGHJKMNPQRSTVWXYZ0","to_step_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'

PATCH /engagements/{engagement}/processes/{process}/flows/{flow}

Write engagements.analysis.flows.update

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).
flow path
Identifier (ULID).

Body application/json

  • condition_label string | null

    length: at most 255

  • variant_id string | null

    length: exactly 26

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 -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/processes/{process}/flows/{flow}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"condition_label":"…","variant_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'

DELETE /engagements/{engagement}/processes/{process}/flows/{flow}

Write engagements.analysis.flows.destroy

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).
flow path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 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 DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/processes/{process}/flows/{flow}" \
  -H "Authorization: Bearer pat_…"

PUT /engagements/{engagement}/processes/{process}/layout

Write engagements.analysis.processes.layout

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).

Body application/json

  • nodes array<object> required
  • edges array<object> | null
  • lanes string | null

    one of none actor population

  • manual array<string>

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 -X PUT "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/processes/{process}/layout" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"nodes":[]}'

POST /engagements/{engagement}/processes/{process}/merge

Write engagements.analysis.processes.merge

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).

Body application/json

  • into_process_id string required

    length: exactly 26

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}/processes/{process}/merge" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"into_process_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'

POST /engagements/{engagement}/processes/{process}/review

Write engagements.analysis.processes.review

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).

Body application/json

  • review_status object required

    one of proposed validated rejected

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}/processes/{process}/review" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"review_status":"proposed"}'

POST /engagements/{engagement}/processes/{process}/split

Write engagements.analysis.processes.split

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).

Body application/json

  • step_ids array<string> required

    items: at least 1

  • new_name string required

    length: at most 255

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}/processes/{process}/split" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"step_ids":[],"new_name":"…"}'

POST /engagements/{engagement}/processes/{process}/steps

Write engagements.analysis.steps.store

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).

Body application/json

  • name string required

    length: at most 255

  • description string | null

    length: at most 2000

  • step_type object

    one of start task decision wait end

  • position integer | null

    at least 1

  • after_step_id string | null

    length: exactly 26

  • actor_id string | null

    length: exactly 26

  • actor_role string | null

    length: at most 255

  • tool_id string | null

    length: exactly 26

  • input_text string | null

    length: at most 255

  • output_text string | null

    length: at most 255

  • duration_estimate array<object> | null
  • volume_estimate array<object> | null

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}/processes/{process}/steps" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

PATCH /engagements/{engagement}/processes/{process}/steps/{step}

Write engagements.analysis.steps.update

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).
step path
Identifier (ULID).

Body application/json

  • name string

    length: at most 255

  • description string | null

    length: at most 2000

  • step_type object

    one of start task decision wait end

  • position integer

    at least 1

  • actor_id string | null

    length: exactly 26

  • actor_role string | null

    length: at most 255

  • tool_id string | null

    length: exactly 26

  • input_text string | null

    length: at most 255

  • output_text string | null

    length: at most 255

  • duration_estimate array<object> | null
  • volume_estimate array<object> | null

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 -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/processes/{process}/steps/{step}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","description":"…","step_type":"start"}'

DELETE /engagements/{engagement}/processes/{process}/steps/{step}

Write engagements.analysis.steps.destroy

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).
step path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 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 DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/processes/{process}/steps/{step}" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/processes/{process}/steps/{step}/evidences

Read engagements.analysis.steps.evidences

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).
step 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}/processes/{process}/steps/{step}/evidences" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/processes/{process}/variants

Write engagements.analysis.variants.store

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).

Body application/json

  • name string required

    length: at most 255

  • condition_text string | null

    length: at most 2000

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}/processes/{process}/variants" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

PATCH /engagements/{engagement}/processes/{process}/variants/{variant}

Write engagements.analysis.variants.update

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).
variant path
Identifier (ULID).

Body application/json

  • name string required

    length: at most 255

  • condition_text string | null

    length: at most 2000

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 -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/processes/{process}/variants/{variant}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

DELETE /engagements/{engagement}/processes/{process}/variants/{variant}

Write engagements.analysis.variants.destroy

Parameters

engagement path
Identifier (ULID).
process path
Identifier (ULID).
variant path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 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 DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/processes/{process}/variants/{variant}" \
  -H "Authorization: Bearer pat_…"

GET /engagements/{engagement}/tools

Read engagements.analysis.tools.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}/tools" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/tools

Write engagements.analysis.tools.store

Parameters

engagement path
Identifier (ULID).

Body application/json

  • name string required

    length: at most 255

  • kind object

    one of software spreadsheet email paper messaging other

  • aliases array<string>

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}/tools" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

PATCH /engagements/{engagement}/tools/{tool}

Write engagements.analysis.tools.update

Parameters

engagement path
Identifier (ULID).
tool path
Identifier (ULID).

Body application/json

  • name string

    length: at most 255

  • kind object

    one of software spreadsheet email paper messaging other

  • aliases array<string>

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 -X PATCH "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/tools/{tool}" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","kind":"software","aliases":[]}'

DELETE /engagements/{engagement}/tools/{tool}

Write engagements.analysis.tools.destroy

Parameters

engagement path
Identifier (ULID).
tool path
Identifier (ULID).

Responses

  • 204 Deleted, no content.
  • 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 DELETE "https://{your-workspace}.tellmehow.io/api/v1/engagements/{engagement}/tools/{tool}" \
  -H "Authorization: Bearer pat_…"

POST /engagements/{engagement}/tools/{tool}/merge

Write engagements.analysis.tools.merge

Parameters

engagement path
Identifier (ULID).
tool path
Identifier (ULID).

Body application/json

  • into_tool_id string required

    length: exactly 26

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}/tools/{tool}/merge" \
  -H "Authorization: Bearer pat_…" \
  -H "Content-Type: application/json" \
  -d '{"into_tool_id":"01JABCDEFGHJKMNPQRSTVWXYZ0"}'