Guides
Authentication and scopes
Send an API key created by a workspace mentor in Settings as Authorization: Bearer mpk_…. Cookies are never used. Keys expire, can be rotated with a grace period, and can be revoked; a revoked or expired key fails the next request with 401 invalid_credentials.
Each operation needs the scope shown next to it. A key without it gets 403 insufficient_scope. A key acts as the mentor who created it, inside that mentor's workspace only; ids from another workspace are always 404.
Private fields
Some fields are private, for example mentor notes, recording summaries, transcripts and routing emails. They are included only when the key was created with private access, and are omitted (not set to null) otherwise. Recording content is also withheld for recordings captured through another mentor's provider connection.
Errors
Errors use one envelope: {"error": {"code", "message", "requestId"}} plus fieldErrors (validation_failed), resetAt (quota_exhausted) or conflict (mentee conflicts). Branch on code, not on message. The table below lists every code the API returns and its status. 410 Gone is not used.
New error codes may be added within v1; treat an unknown code by its HTTP status.
List responses are {"data": [...], "nextCursor": string|null}. Pass nextCursor as cursor to get the next page; null means the last page. Cursors are opaque and only valid with the filters they were issued for (otherwise 422 validation_failed). Page sizes are set with limit within each operation's maximum.
Meeting transcripts page separately with transcriptCursor; if the transcript changed meanwhile the response is 409 revision_conflict and you restart without a cursor.
Rate limits and metering
Requests are limited per minute and per month for the workspace's plan. Successful and error responses after authentication carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds). Above the minute limit the response is 429 rate_limited; when the monthly allowance is used it is 429 quota_exhausted with resetAt. Both carry Retry-After.
Requests are counted after authentication, scope and rate checks, including 4xx responses. 5xx responses, idempotent replays and webhook delivery replays are not counted, and neither are 429 responses.
Idempotency
Every write (POST, PATCH, DELETE) needs an Idempotency-Key header (16 to 128 letters, digits, - or _); without it the response is 400 idempotency_key_required. Retrying with the same key and the same request returns the stored result with Idempotent-Replayed: true and changes nothing. Reusing a key for a different request is 409 idempotency_conflict. Keys are kept for 30 days per API key lineage.
Concurrency (If-Match)
PATCH /api/v1/tasks/{taskId} needs If-Match with the revision you read (for example "3"). If the task changed in the meantime, on the web or by another integration, the response is 409 revision_conflict and nothing is written. Fetch the task again and retry.
Webhooks
Webhooks follow Standard Webhooks. Each POST carries webhook-id, webhook-timestamp and webhook-signature. Verify the signature over the raw body before parsing, reject timestamps more than 5 minutes old, and deduplicate on webhook-id: delivery is at least once and unordered (order by data.revision).
Payloads contain identifiers and non-private fields only, built when each attempt is sent with the endpoint key's current scopes and private access. origin carries the channel and the operationId/correlationId returned in your write receipts (never a credential id); skip events whose origin.operationId is one of your own writes. A decision event whose decision is no longer visible to the key is cancelled with EVENT_NOT_VISIBLE and not sent.
Failed deliveries are retried with exponential backoff and jitter, up to 8 attempts. An endpoint that keeps failing is disabled after at least 15 consecutive failures over 24 hours. If the workspace loses API access, deliveries wait and expire after the normal retry window (about 64 minutes). Replay any logged delivery with the same webhook-id.
Versioning and deprecation
The major version is in the path (/api/v1). Within v1, changes are additive only: new operations, new optional request fields, new response fields, new event types, new enum values and new error codes. Build clients that ignore unknown fields and handle unknown enum values.
Breaking changes ship only in a new major version. No v1 operation is deprecated today, and Deprecation and Sunset headers are not sent.
Workflow runs
Starting a run needs two scopes: workflows:run and mentees:read. Reading a run needs workflows:read and mentees:read. A key holding only one of the pair gets 403 insufficient_scope, and that refusal is not counted against the request allowance.
Send an Idempotency-Key. The same key with the same body returns the stored result: 200 with Idempotent-Replayed for an admitted request, or the same 409 workflow_not_admitted for one that admitted nobody. The same key with a different body is 409 idempotency_conflict. Invalid requests (422) are never stored, so you may correct and retry them under the same key. Repeated mentee ids in one request are refused rather than merged, and the list is sorted before it is compared, so [b, a] and [a, b] are the same request.
A request that is valid but admits nobody - the workflow is paused, the selection is over the fan-out limit, or the workflow run allowance is used up - returns 409 workflow_not_admitted with the reason and the recorded invocationId. No mentee ids, counts, caps or allowance figures are returned.
Runs execute under the authority of the mentor who turned the workflow on. Revoking or rotating the key does not cancel a run that was already admitted; cancel it in the app. Run status never returns names, message text, condition operands, fact names or the ids of the people who authored or authorised the workflow.
Webhooks
List webhook endpoints
get/api/v1/webhooks
Endpoints created by this key's lineage (the key and its rotated successors).
- Operation
- webhook.list
- Scope
- webhooks:write
- Idempotency-Key
- Not used
Response 200
Schema: WebhookEndpointList
Response of webhook.list| Field | Type | Required | Notes |
|---|
| data | array of WebhookEndpoint | Yes | |
|---|
Errors
Create a webhook endpoint
post/api/v1/webhooks
Subscribes a public https URL to event types. Each event type needs its read scope. The signing secret is returned once.
- Operation
- webhook.create
- Scope
- webhooks:write
- Idempotency-Key
- Required
Parameters
Parameters of webhook.create| Name | In | Type | Required | Notes |
|---|
| Idempotency-Key | header | string | Yes | Unique per logical write. Retrying with the same key and body returns the original result; the same key with a different body is 409 idempotency_conflict. Keys are scoped to the API key lineage and kept for 30 days. Pattern ^[A-Za-z0-9_-]{16,128}$. |
|---|
Request body
Schema: WebhookEndpointCreateRequest
Request body of webhook.create| Field | Type | Required | Notes |
|---|
| url | string | Yes | Public https URL; no credentials, fragment, private host or private IP. Length 0 to 2048. |
|---|
| eventTypes | array of WebhookEventType | Yes | Each type needs its read scope on the key. Items 1 to 7. |
|---|
| description | string or null | No | Length 0 to 200. |
|---|
Response 201
Schema: WebhookEndpointReceiptResponse
Errors
Get a webhook endpoint
get/api/v1/webhooks/{endpointId}
One endpoint of this key's lineage.
- Operation
- webhook.get
- Scope
- webhooks:write
- Idempotency-Key
- Not used
Parameters
Parameters of webhook.get| Name | In | Type | Required | Notes |
|---|
| endpointId | path | string | Yes | Webhook endpoint id. Pattern ^[A-Za-z0-9_-]{1,128}$. |
|---|
Response 200
Schema: WebhookEndpointResponse
Errors
Update a webhook endpoint
patch/api/v1/webhooks/{endpointId}
Changes url, eventTypes or description, or disables/re-enables the endpoint.
- Operation
- webhook.update
- Scope
- webhooks:write
- Idempotency-Key
- Required
Parameters
Parameters of webhook.update| Name | In | Type | Required | Notes |
|---|
| endpointId | path | string | Yes | Webhook endpoint id. Pattern ^[A-Za-z0-9_-]{1,128}$. |
|---|
| Idempotency-Key | header | string | Yes | Unique per logical write. Retrying with the same key and body returns the original result; the same key with a different body is 409 idempotency_conflict. Keys are scoped to the API key lineage and kept for 30 days. Pattern ^[A-Za-z0-9_-]{16,128}$. |
|---|
Request body
Schema: WebhookEndpointUpdateRequest
Request body of webhook.update| Field | Type | Required | Notes |
|---|
| url | string | No | Length 0 to 2048. |
|---|
| eventTypes | array of WebhookEventType | No | Items 1 to 7. |
|---|
| description | string or null | No | Length 0 to 200. |
|---|
| enabled | boolean | No | false disables (MANUAL); true re-enables MANUAL or FAILURES and clears the failure streak. |
|---|
Response 200
Schema: WebhookEndpointReceiptResponse
Errors
Delete a webhook endpoint
delete/api/v1/webhooks/{endpointId}
Deletes the endpoint, its secrets and its pending deliveries. Finished delivery logs are kept until retention removes them (30 days).
- Operation
- webhook.delete
- Scope
- webhooks:write
- Idempotency-Key
- Required
Parameters
Parameters of webhook.delete| Name | In | Type | Required | Notes |
|---|
| endpointId | path | string | Yes | Webhook endpoint id. Pattern ^[A-Za-z0-9_-]{1,128}$. |
|---|
| Idempotency-Key | header | string | Yes | Unique per logical write. Retrying with the same key and body returns the original result; the same key with a different body is 409 idempotency_conflict. Keys are scoped to the API key lineage and kept for 30 days. Pattern ^[A-Za-z0-9_-]{16,128}$. |
|---|
Response 200
Schema: WebhookEndpointReceiptResponse
Errors
Rotate the signing secret
post/api/v1/webhooks/{endpointId}/rotate-secret
Issues a new secret (returned once). Older secrets stay valid for overlapHours; during the overlap every delivery is signed with each.
- Operation
- webhook.secret.rotate
- Scope
- webhooks:write
- Idempotency-Key
- Required
Parameters
Parameters of webhook.secret.rotate| Name | In | Type | Required | Notes |
|---|
| endpointId | path | string | Yes | Webhook endpoint id. Pattern ^[A-Za-z0-9_-]{1,128}$. |
|---|
| Idempotency-Key | header | string | Yes | Unique per logical write. Retrying with the same key and body returns the original result; the same key with a different body is 409 idempotency_conflict. Keys are scoped to the API key lineage and kept for 30 days. Pattern ^[A-Za-z0-9_-]{16,128}$. |
|---|
Request body (optional)
Schema: WebhookRotateSecretRequest
Request body of webhook.secret.rotate| Field | Type | Required | Notes |
|---|
| overlapHours | integer | No | Range 0 to 24. Default 24. |
|---|
Response 200
Schema: WebhookEndpointReceiptResponse
Errors
List deliveries
get/api/v1/webhooks/{endpointId}/deliveries
Delivery log, newest first: state, attempts, status code, latency and error class only (never payloads).
- Operation
- webhook.delivery.list
- Scope
- webhooks:write
- Idempotency-Key
- Not used
Parameters
Parameters of webhook.delivery.list| Name | In | Type | Required | Notes |
|---|
| endpointId | path | string | Yes | Webhook endpoint id. Pattern ^[A-Za-z0-9_-]{1,128}$. |
|---|
| state | query | string | No | Only this state. One of: PENDING, LEASED, SUCCEEDED, FAILED, CANCELLED, EXPIRED. |
|---|
| cursor | query | string | No | nextCursor from the previous page. Opaque; only valid with the same filters. Length 0 to 512. |
|---|
| limit | query | integer | No | Page size, 1 to 100 (default 25). Range 1 to 100. Default 25. |
|---|
Response 200
Schema: WebhookDeliveryPage
Response of webhook.delivery.list| Field | Type | Required | Notes |
|---|
| data | array of WebhookDelivery | Yes | |
|---|
| nextCursor | string or null | Yes | Opaque cursor for the next page, or null on the last page. Bound to the filters it was issued with. |
|---|
Errors
Replay a delivery
post/api/v1/webhooks/{endpointId}/deliveries/{deliveryId}/replay
Sends a logged delivery again with the same webhook-id. Free. A delivery that is already scheduled is not scheduled twice.
- Operation
- webhook.delivery.replay
- Scope
- webhooks:write
- Idempotency-Key
- Required
- Metering
- Free (not counted)
Parameters
Parameters of webhook.delivery.replay| Name | In | Type | Required | Notes |
|---|
| endpointId | path | string | Yes | Webhook endpoint id. Pattern ^[A-Za-z0-9_-]{1,128}$. |
|---|
| deliveryId | path | string | Yes | Delivery id. Pattern ^[A-Za-z0-9_-]{1,128}$. |
|---|
| Idempotency-Key | header | string | Yes | Unique per logical write. Retrying with the same key and body returns the original result; the same key with a different body is 409 idempotency_conflict. Keys are scoped to the API key lineage and kept for 30 days. Pattern ^[A-Za-z0-9_-]{16,128}$. |
|---|
Response 202
Schema: WebhookReplayReceiptResponse
Errors
Schemas
ErrorCode
Stable machine-readable error code. See x-error-catalog for the HTTP status of each code.
string One of: client_limit_reached, conflict, feature_unavailable, forbidden, idempotency_conflict, idempotency_key_required, insufficient_scope, internal_error, invalid_credentials, not_found, plan_required, precondition_required, quota_exhausted, rate_limited, retry_later, revision_conflict, validation_failed, workflow_not_admitted.
Error
Fields of Error| Field | Type | Required | Notes |
|---|
| error | object | Yes | |
|---|
DecisionReview
Fields of DecisionReview| Field | Type | Required | Notes |
|---|
| status | string | Yes | One of: NOT_REVIEWED, REVIEWED. |
|---|
| reviewedContentRevision | integer or null | Yes | |
|---|
| reviewedAt | string (date-time) or null | Yes | |
|---|
| reviewerUserId | string or null | Yes | |
|---|
DecisionPassage
Fields of DecisionPassage| Field | Type | Required | Notes |
|---|
| segmentIndex | integer | Yes | |
|---|
| startOffset | integer | Yes | |
|---|
| endOffset | integer | Yes | |
|---|
| quote | string | Yes | |
|---|
| speaker | string or null | Yes | |
|---|
| startSeconds | number or null | Yes | |
|---|
DecisionSource
Fields of DecisionSource| Field | Type | Required | Notes |
|---|
| role | string | Yes | One of: ORIGIN, CORROBORATION. |
|---|
| provider | string | Yes | |
|---|
| meetingTitle | string | Yes | |
|---|
| sourceDate | string or null | Yes | |
|---|
| sourceDateKind | string or null | Yes | |
|---|
| linkedAt | string (date-time) | Yes | |
|---|
| sourceUrl | string or null | No | Private.Private field: present only when the API key has private access, on the detail read only, and never for a recording bound to another mentor's connection. |
|---|
| passages | array of DecisionPassage | No | Private.Private field: present only when the API key has private access, on the detail read only, and never for a recording bound to another mentor's connection. |
|---|
Decision
Fields of Decision| Field | Type | Required | Notes |
|---|
| id | string | Yes | |
|---|
| menteeProfileId | string | Yes | |
|---|
| title | string | Yes | |
|---|
| body | string | Yes | |
|---|
| agreedOn | string (date) or null | Yes | |
|---|
| sourceKind | string | Yes | One of: MANUAL, AI_EXTRACTED. |
|---|
| revision | integer | Yes | Range 1 to any. |
|---|
| chronologyDate | string (date) | No | Private.Present when the date is the agreed date; a date derived from an imported source is private. |
|---|
| chronologyBasis | string | No | Private.Omitted together with chronologyDate. One of: AGREED_ON, SOURCE_DATE, IMPORTED_DATE. |
|---|
| addedAt | string (date-time) | Yes | |
|---|
| updatedAt | string (date-time) | Yes | |
|---|
| createdByUserId | string | Yes | |
|---|
| review | DecisionReview or any or null | No | Private.Private field: present only when the API key has private access. |
|---|
| sources | array of DecisionSource | No | Private.Private field: present only when the API key has private access. |
|---|
DecisionCreateRequest
Fields of DecisionCreateRequest| Field | Type | Required | Notes |
|---|
| menteeProfileId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,128}$. |
|---|
| title | string | Yes | Length 1 to 200. |
|---|
| body | string | Yes | Length 0 to 10000. |
|---|
| agreedOn | string (date) | Yes | |
|---|
DecisionReceipt
Fields of DecisionReceipt| Field | Type | Required | Notes |
|---|
| id | string | Yes | |
|---|
| menteeProfileId | string | Yes | |
|---|
| revision | integer | Yes | |
|---|
| status | string | Yes | One of: ACTIVE. |
|---|
| operationId | string | Yes | |
|---|
| createdAt | string (date-time) | Yes | |
|---|
DecisionPage
Fields of DecisionPage| Field | Type | Required | Notes |
|---|
| data | array of Decision | Yes | |
|---|
| nextCursor | string or null | Yes | Opaque cursor for the next page, or null on the last page. Bound to the filters it was issued with. |
|---|
DecisionResponse
Fields of DecisionResponse| Field | Type | Required | Notes |
|---|
| data | Decision | Yes | |
|---|
DecisionReceiptResponse
Fields of DecisionReceiptResponse| Field | Type | Required | Notes |
|---|
| data | DecisionReceipt | Yes | |
|---|
MenteeSummary
Fields of MenteeSummary| Field | Type | Required | Notes |
|---|
| id | string | Yes | |
|---|
| externalId | string or null | Yes | |
|---|
| name | string | Yes | |
|---|
| email | string | Yes | |
|---|
| status | string | Yes | One of: ACTIVE, PAUSED, ARCHIVED, LOCKED. |
|---|
| company | string or null | Yes | |
|---|
| website | string or null | Yes | |
|---|
| phone | string or null | Yes | |
|---|
| timeZone | string or null | Yes | |
|---|
| engagementStart | string (date-time) or null | Yes | |
|---|
| accountActive | boolean | Yes | |
|---|
| accountSetUp | boolean | Yes | |
|---|
| createdAt | string (date-time) | Yes | |
|---|
MenteeDetail
Fields of MenteeDetail| Field | Type | Required | Notes |
|---|
| id | string | Yes | |
|---|
| externalId | string or null | Yes | |
|---|
| name | string | Yes | |
|---|
| email | string | Yes | |
|---|
| status | string | Yes | One of: ACTIVE, PAUSED, ARCHIVED, LOCKED. |
|---|
| company | string or null | Yes | |
|---|
| website | string or null | Yes | |
|---|
| phone | string or null | Yes | |
|---|
| timeZone | string or null | Yes | |
|---|
| engagementStart | string (date-time) or null | Yes | |
|---|
| accountActive | boolean | Yes | |
|---|
| accountSetUp | boolean | Yes | |
|---|
| createdAt | string (date-time) | Yes | |
|---|
| tidycalBookingUrl | string or null | Yes | |
|---|
| nextCallDate | string (date-time) or null | Yes | |
|---|
| invitedAt | string (date-time) or null | Yes | |
|---|
| sharedGoal | object | Yes | |
|---|
| privateNotes | string or null | No | Private.Private field: present only when the API key has private access (mentor notes). |
|---|
QuestionnaireSelection
Fields of QuestionnaireSelection| Field | Type | Required | Notes |
|---|
| templateId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,128}$. |
|---|
| publishedVersionId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,128}$. |
|---|
| due | object or any or null | No | Default null. |
|---|
| expiresAt | string (date-time) or null | No | Default null. |
|---|
| message | string or null | No | Length 0 to 10000. Default null. |
|---|
MenteeCreateRequest
Fields of MenteeCreateRequest| Field | Type | Required | Notes |
|---|
| name | string | Yes | Length 1 to 200. |
|---|
| email | string (email) | Yes | |
|---|
| company | string or null | No | Length 0 to 200. |
|---|
| website | string or null | No | Length 0 to 2000. |
|---|
| phone | string or null | No | Length 0 to 100. |
|---|
| tidycalBookingUrl | string or null | No | Length 0 to 2000. |
|---|
| timeZone | string | No | Default "UTC". |
|---|
| sendInvite | boolean | Yes | Required. true queues one invitation email to the mentee. |
|---|
| questionnaires | array of QuestionnaireSelection | Yes | Non-empty needs assignments:write as well. Items 0 to 20. |
|---|
| externalId | string | No | Your system's id (for example a CRM contact id). Unique per workspace. Pattern ^[A-Za-z0-9._:@|/-]{1,128}$. |
|---|
MenteeCreateReceipt
Fields of MenteeCreateReceipt| Field | Type | Required | Notes |
|---|
| menteeProfileId | string | Yes | |
|---|
| externalId | string or null | Yes | |
|---|
| assignmentIds | array of string | Yes | |
|---|
| issuedAssignmentIds | array of string | Yes | |
|---|
| reusedAssignmentIds | array of string | Yes | |
|---|
| invitation | object or any or null | Yes | |
|---|
| operationId | string | Yes | |
|---|
| createdAt | string (date-time) | Yes | |
|---|
MenteePage
Fields of MenteePage| Field | Type | Required | Notes |
|---|
| data | array of MenteeSummary | Yes | |
|---|
| nextCursor | string or null | Yes | Opaque cursor for the next page, or null on the last page. Bound to the filters it was issued with. |
|---|
MenteeResponse
Fields of MenteeResponse| Field | Type | Required | Notes |
|---|
| data | MenteeDetail | Yes | |
|---|
MenteeCreateReceiptResponse
TranscriptSegment
Fields of TranscriptSegment| Field | Type | Required | Notes |
|---|
| index | integer | Yes | |
|---|
| speaker | string or null | Yes | Length 0 to 256. |
|---|
| timestamp | string or null | Yes | Length 0 to 64. |
|---|
| startTime | number or null | Yes | |
|---|
| textOffset | integer | Yes | UTF-16 offset of text within the segment. |
|---|
| text | string | Yes | |
|---|
| continues | boolean | Yes | More text of this segment follows on the next page. |
|---|
TranscriptPage
Fields of TranscriptPage| Field | Type | Required | Notes |
|---|
| segments | array of TranscriptSegment | Yes | |
|---|
| nextCursor | string or null | Yes | Pass as transcriptCursor. |
|---|
Meeting
Fields of Meeting| Field | Type | Required | Notes |
|---|
| id | string | Yes | |
|---|
| menteeProfileId | string | Yes | |
|---|
| title | string | Yes | |
|---|
| date | string (date-time) | Yes | |
|---|
| duration | integer or null | Yes | |
|---|
| provider | string or null | Yes | |
|---|
| summaryOneLiner | string or null | No | Private.Private field: present only when the API key has private access, never for another mentor's recording. |
|---|
| recordingUrl | string or null | No | Private.Private field: present only when the API key has private access, never for another mentor's recording. |
|---|
MeetingDetail
Fields of MeetingDetail| Field | Type | Required | Notes |
|---|
| id | string | Yes | |
|---|
| menteeProfileId | string | Yes | |
|---|
| title | string | Yes | |
|---|
| date | string (date-time) | Yes | |
|---|
| duration | integer or null | Yes | |
|---|
| provider | string or null | Yes | |
|---|
| summaryOneLiner | string or null | No | Private.Private field: present only when the API key has private access, never for another mentor's recording. |
|---|
| recordingUrl | string or null | No | Private.Private field: present only when the API key has private access, never for another mentor's recording. |
|---|
| summary | string or null | No | Private.Private field: present only when the API key has private access. First page only (no transcriptCursor); at most 16,000 UTF-8 bytes. |
|---|
| summaryTruncated | boolean | No | Private.Private field: present only when the API key has private access. First page only. |
|---|
| transcript | TranscriptPage or any or null | No | Private.Private field: present only when the API key has private access. One bounded page (segments at most 64,000 UTF-8 bytes including the summary). |
|---|
MeetingPage
Fields of MeetingPage| Field | Type | Required | Notes |
|---|
| data | array of Meeting | Yes | |
|---|
| nextCursor | string or null | Yes | Opaque cursor for the next page, or null on the last page. Bound to the filters it was issued with. |
|---|
MeetingResponse
Fields of MeetingResponse| Field | Type | Required | Notes |
|---|
| data | MeetingDetail | Yes | |
|---|
PublishedQuestionnaire
Fields of PublishedQuestionnaire| Field | Type | Required | Notes |
|---|
| templateId | string | Yes | |
|---|
| publishedVersionId | string | Yes | |
|---|
| title | string | Yes | |
|---|
| version | integer | Yes | |
|---|
| publishedAt | string (date-time) | Yes | |
|---|
| onboardingDefault | boolean | Yes | |
|---|
QuestionnairePage
Fields of QuestionnairePage| Field | Type | Required | Notes |
|---|
| data | array of PublishedQuestionnaire | Yes | |
|---|
| nextCursor | string or null | Yes | Opaque cursor for the next page, or null on the last page. Bound to the filters it was issued with. |
|---|
AssignmentRequest
Fields of AssignmentRequest| Field | Type | Required | Notes |
|---|
| questionnaires | array of QuestionnaireSelection | Yes | Items 1 to 20. |
|---|
AssignmentReceipt
Fields of AssignmentReceipt| Field | Type | Required | Notes |
|---|
| menteeProfileId | string | Yes | |
|---|
| assignmentIds | array of string | Yes | |
|---|
| issuedAssignmentIds | array of string | Yes | |
|---|
| reusedAssignmentIds | array of string | Yes | Already open ordinary assignments; nothing duplicated. |
|---|
| operationId | string | Yes | |
|---|
| createdAt | string (date-time) | Yes | |
|---|
AssignmentReceiptResponse
Task
Fields of Task| Field | Type | Required | Notes |
|---|
| id | string | Yes | |
|---|
| menteeProfileId | string | Yes | |
|---|
| title | string | Yes | |
|---|
| details | string or null | Yes | |
|---|
| assignee | string or null | Yes | |
|---|
| status | string | Yes | One of: SUGGESTED, ACTIVE, ARCHIVED, DISMISSED. |
|---|
| isCompleted | boolean | Yes | |
|---|
| completedAt | string (date-time) or null | Yes | |
|---|
| deadline | string (date-time) or null | Yes | |
|---|
| isFocus | boolean | Yes | |
|---|
| source | string | Yes | |
|---|
| meeting | object or any or null | Yes | |
|---|
| archivedAt | string (date-time) or null | Yes | |
|---|
| revision | integer | Yes | Range 1 to any. |
|---|
| createdAt | string (date-time) | Yes | |
|---|
| updatedAt | string (date-time) | Yes | |
|---|
| assigneeEmail | string or null | No | Private.Private field: present only when the API key has private access; withheld for a task imported from another mentor's recording. |
|---|
TaskCreateRequest
Fields of TaskCreateRequest| Field | Type | Required | Notes |
|---|
| menteeProfileId | string | Yes | Pattern ^[A-Za-z0-9_-]{1,128}$. |
|---|
| title | string | Yes | Length 1 to 1000. |
|---|
| details | string or null | No | At most 10,000 characters after trimming. |
|---|
| assigneeTarget | string | No | One of: MENTEE, MENTOR, UNASSIGNED. Default "UNASSIGNED". |
|---|
| deadline | string or null | No | YYYY-MM-DD or an ISO 8601 date-time with a time zone. Length 0 to 40. |
|---|
| meetingId | string or null | No | |
|---|
| isFocus | boolean | No | Default false. |
|---|
TaskUpdateRequest
Fields of TaskUpdateRequest| Field | Type | Required | Notes |
|---|
| title | string | No | Length 1 to 1000. |
|---|
| details | string or null | No | |
|---|
| assigneeTarget | string | No | One of: MENTEE, MENTOR, UNASSIGNED. |
|---|
| deadline | string or null | No | YYYY-MM-DD or an ISO 8601 date-time with a time zone. Length 0 to 40. |
|---|
| isFocus | boolean | No | |
|---|
| isCompleted | boolean | No | |
|---|
| status | string | No | One of: SUGGESTED, ACTIVE, ARCHIVED, DISMISSED. |
|---|
TaskReceipt
Fields of TaskReceipt| Field | Type | Required | Notes |
|---|
| id | string | Yes | |
|---|
| menteeProfileId | string | Yes | |
|---|
| revision | integer | Yes | |
|---|
| status | string | Yes | One of: SUGGESTED, ACTIVE, ARCHIVED, DISMISSED. |
|---|
| operationId | string | Yes | |
|---|
| completedAt | string (date-time) or null | Yes | |
|---|
TaskPage
Fields of TaskPage| Field | Type | Required | Notes |
|---|
| data | array of Task | Yes | |
|---|
| nextCursor | string or null | Yes | Opaque cursor for the next page, or null on the last page. Bound to the filters it was issued with. |
|---|
TaskResponse
Fields of TaskResponse| Field | Type | Required | Notes |
|---|
| data | Task | Yes | |
|---|
TaskReceiptResponse
Fields of TaskReceiptResponse| Field | Type | Required | Notes |
|---|
| data | TaskReceipt | Yes | |
|---|
WebhookEventType
string One of: decision.created, decision.updated, mentee.created, questionnaire.assignment.created, questionnaire.assignment.submitted, task.created, task.updated, workflow.run.ended.
WebhookEndpoint
Fields of WebhookEndpoint| Field | Type | Required | Notes |
|---|
| id | string | Yes | |
|---|
| url | string (uri) | Yes | |
|---|
| description | string or null | Yes | |
|---|
| eventTypes | array of WebhookEventType | Yes | |
|---|
| status | string | Yes | One of: ACTIVE, DISABLED. |
|---|
| disabledReason | string or null | Yes | One of: MANUAL, CREDENTIAL_REVOKED, CREDENTIAL_EXPIRED, FAILURES, null. |
|---|
| disabledAt | string (date-time) or null | Yes | |
|---|
| consecutiveFailures | integer | Yes | |
|---|
| revision | integer | Yes | |
|---|
| createdAt | string (date-time) | Yes | |
|---|
| updatedAt | string (date-time) | Yes | |
|---|
| secrets | array of object | Yes | Unexpired signing secrets (metadata only; never the secret). |
|---|
WebhookEndpointCreateRequest
Fields of WebhookEndpointCreateRequest| Field | Type | Required | Notes |
|---|
| url | string | Yes | Public https URL; no credentials, fragment, private host or private IP. Length 0 to 2048. |
|---|
| eventTypes | array of WebhookEventType | Yes | Each type needs its read scope on the key. Items 1 to 7. |
|---|
| description | string or null | No | Length 0 to 200. |
|---|
WebhookEndpointUpdateRequest
Fields of WebhookEndpointUpdateRequest| Field | Type | Required | Notes |
|---|
| url | string | No | Length 0 to 2048. |
|---|
| eventTypes | array of WebhookEventType | No | Items 1 to 7. |
|---|
| description | string or null | No | Length 0 to 200. |
|---|
| enabled | boolean | No | false disables (MANUAL); true re-enables MANUAL or FAILURES and clears the failure streak. |
|---|
WebhookRotateSecretRequest
Fields of WebhookRotateSecretRequest| Field | Type | Required | Notes |
|---|
| overlapHours | integer | No | Range 0 to 24. Default 24. |
|---|
WebhookEndpointReceipt
Fields of WebhookEndpointReceipt| Field | Type | Required | Notes |
|---|
| id | string | Yes | |
|---|
| status | string | Yes | One of: ACTIVE, UPDATED, ROTATED, DELETED. |
|---|
| revision | integer | Yes | |
|---|
| operationId | string | Yes | |
|---|
| secret | string or null | No | create and rotate-secret only: the whsec_ signing secret, shown once; null on an idempotent replay. |
|---|
WebhookDelivery
Fields of WebhookDelivery| Field | Type | Required | Notes |
|---|
| id | string | Yes | |
|---|
| webhookId | string | Yes | The webhook-id header value (the event id); stable across retries and replays. |
|---|
| eventType | WebhookEventType | Yes | |
|---|
| state | string | Yes | One of: PENDING, LEASED, SUCCEEDED, FAILED, CANCELLED, EXPIRED. |
|---|
| attempts | integer | Yes | |
|---|
| replayCount | integer | Yes | |
|---|
| lastStatusCode | integer or null | Yes | |
|---|
| lastErrorClass | string or null | Yes | |
|---|
| lastLatencyMs | integer or null | Yes | |
|---|
| deliveredAt | string (date-time) or null | Yes | |
|---|
| nextAttemptAt | string (date-time) or null | Yes | |
|---|
| createdAt | string (date-time) | Yes | |
|---|
| log | array of object | Yes | Items 0 to 20. |
|---|
WebhookReplayReceipt
Fields of WebhookReplayReceipt| Field | Type | Required | Notes |
|---|
| deliveryId | string | Yes | |
|---|
| webhookId | string | Yes | |
|---|
| state | string | Yes | One of: PENDING, LEASED, SUCCEEDED, FAILED, CANCELLED, EXPIRED. |
|---|
| replayCount | integer | Yes | |
|---|
| operationId | string | Yes | |
|---|
WebhookEndpointList
Fields of WebhookEndpointList| Field | Type | Required | Notes |
|---|
| data | array of WebhookEndpoint | Yes | |
|---|
WebhookEndpointResponse
Fields of WebhookEndpointResponse| Field | Type | Required | Notes |
|---|
| data | WebhookEndpoint | Yes | |
|---|
WebhookEndpointReceiptResponse
WebhookDeliveryPage
Fields of WebhookDeliveryPage| Field | Type | Required | Notes |
|---|
| data | array of WebhookDelivery | Yes | |
|---|
| nextCursor | string or null | Yes | Opaque cursor for the next page, or null on the last page. Bound to the filters it was issued with. |
|---|
WebhookReplayReceiptResponse
WebhookEvent
Webhook request body (POSTed to your endpoint). Not an API response.
Fields of WebhookEvent| Field | Type | Required | Notes |
|---|
| id | string | Yes | Equals the webhook-id header. |
|---|
| type | WebhookEventType | Yes | |
|---|
| timestamp | string (date-time) | Yes | |
|---|
| workspaceId | string | Yes | |
|---|
| routine | boolean | Yes | false when the event comes from checking a client's past calls (historical extraction), true for live work. Non-routine events never trigger workflows. |
|---|
| data | object | Yes | |
|---|
| origin | object | Yes | |
|---|
WorkflowRunStartRequest
Unknown fields are refused with 422 validation_failed.
Fields of WorkflowRunStartRequest| Field | Type | Required | Notes |
|---|
| menteeProfileIds | array of string | Yes | The mentees to start a run for. Between 1 and 100 DIFFERENT ids: a repeated id is refused with 422 validation_failed (INVALID_SELECTION), never de-duplicated. Order does not matter - the list is sorted before it is hashed, so [b, a] and [a, b] are the same request under one Idempotency-Key. Items 1 to 100. |
|---|
WorkflowRunReceipt
Fields of WorkflowRunReceipt| Field | Type | Required | Notes |
|---|
| invocationId | string | Yes | The recorded trigger instance for this request. |
|---|
| workflowId | string | Yes | The workflow that was started. |
|---|
| outcome | string | Yes | Admission is all or none. A request that admitted nobody is 409 workflow_not_admitted, not a receipt. One of: ADMITTED. |
|---|
| admittedCount | integer | Yes | Number of runs created (equal to the number of ids sent). |
|---|
| runs | array of object | Yes | |
|---|
WorkflowRunReceiptResponse
WorkflowRunState
Run state. Treat an unlisted value as a new state rather than an error.
string One of: ADMITTED, ACTIVE, PAUSED_REAUTHORIZE, SUCCEEDED, SKIPPED, FAILED, CANCELLED, NOT_STARTED.
WorkflowRunRedactedState
Redacted run state. ADMITTED, ACTIVE and PAUSED_REAUTHORIZE all read IN_PROGRESS; every ended run reads ENDED.
string One of: IN_PROGRESS, ENDED.
WorkflowRunStep
Fields of WorkflowRunStep| Field | Type | Required | Notes |
|---|
| id | string | Yes | Step execution id. |
|---|
| position | integer | Yes | Position in the workflow (the start step is -1). |
|---|
| kind | string | Yes | One of: start, condition, delay, action. |
|---|
| actionType | string or null | Yes | Action steps only. Never the action's settings, message text or referenced record. |
|---|
| state | string | Yes | Step state. |
|---|
| outcomeCode | string or null | Yes | Stable outcome code. Never a condition operand, fact name or value. |
|---|
| wakeAt | string (date-time) or null | Yes | |
|---|
| completedAt | string (date-time) or null | Yes | |
|---|
| retryCount | integer | Yes | |
|---|
| suspended | boolean | Yes | |
|---|
WorkflowRunFull
Fields of WorkflowRunFull| Field | Type | Required | Notes |
|---|
| id | string | Yes | Run id. |
|---|
| workflowId | string | Yes | The workflow this run belongs to. |
|---|
| invocationId | string | Yes | The trigger instance that admitted this run. |
|---|
| menteeProfileId | string | Yes | The mentee this run is for. |
|---|
| state | WorkflowRunState | Yes | |
|---|
| outcomeCode | string or null | Yes | Stable outcome code for an ended run. |
|---|
| versionNumber | integer or null | Yes | The workflow version this run is pinned to. |
|---|
| startedVia | string or null | Yes | How this run was started. Null only if the originating trigger instance no longer exists. One of: WEB, BACKGROUND, EXTERNAL, null. |
|---|
| createdAt | string (date-time) | Yes | |
|---|
| startedAt | string (date-time) or null | Yes | |
|---|
| endedAt | string (date-time) or null | Yes | |
|---|
| revision | integer | Yes | |
|---|
| steps | array of WorkflowRunStep | Yes | |
|---|
WorkflowRunRedacted
Returned for a run whose workflow reads questionnaire answers, to a key without private access.
Fields of WorkflowRunRedacted| Field | Type | Required | Notes |
|---|
| id | string | Yes | Run id. |
|---|
| workflowId | string | Yes | The workflow this run belongs to. |
|---|
| invocationId | string | Yes | The trigger instance that admitted this run. |
|---|
| menteeProfileId | string | Yes | The mentee this run is for. |
|---|
| state | WorkflowRunRedactedState | Yes | |
|---|
| startedVia | string or null | Yes | How this run was started. Null only if the originating trigger instance no longer exists. One of: WEB, BACKGROUND, EXTERNAL, null. |
|---|
| createdAt | string (date-time) | Yes | |
|---|
WorkflowRun
Full or redacted, decided per request. A run is redacted when the workflow version it is pinned to either uses a questionnaire condition (questionnaire status, submitted, score or a readable answer) or is started by a questionnaire event, AND the key does not have private access. Tell them apart by the state value: a redacted run reports only IN_PROGRESS or ENDED.
WorkflowRunFull or WorkflowRunRedacted
WorkflowRunResponse
Fields of WorkflowRunResponse| Field | Type | Required | Notes |
|---|
| data | WorkflowRun | Yes | |
|---|
WorkflowSummary
A workflow this API key can start runs of: not archived, metered, and with a manual-trigger active version.
Fields of WorkflowSummary| Field | Type | Required | Notes |
|---|
| id | string | Yes | Workflow id. |
|---|
| name | string | Yes | The workflow name as the mentor wrote it. |
|---|
| state | string | Yes | ACTIVE accepts run requests; PAUSED is listed but refuses them with 409 workflow_not_admitted. One of: ACTIVE, PAUSED. |
|---|
| manualRunAvailable | boolean | Yes | True when POST /api/v1/workflows/{workflowId}/runs can admit a run right now. |
|---|
| fanOutCap | integer | Yes | Maximum number of mentees one run request may select on this plan. |
|---|
| updatedAt | string (date-time) | Yes | When the workflow was last changed. |
|---|
WorkflowPage
Fields of WorkflowPage| Field | Type | Required | Notes |
|---|
| data | array of WorkflowSummary | Yes | |
|---|
| nextCursor | string or null | Yes | Opaque cursor for the next page, or null on the last page. Bound to this operation. |
|---|
WorkflowRunEvent
Fields of WorkflowRunEvent| Field | Type | Required | Notes |
|---|
| workflowId | string | Yes | |
|---|
| invocationId | string | Yes | |
|---|
| state | string | Yes | |
|---|
| outcomeCode | string or null | Yes | |
|---|
| startedVia | string or null | Yes | One of: WEB, BACKGROUND, EXTERNAL, null. |
|---|
| createdAt | string (date-time) | Yes | |
|---|
| startedAt | string (date-time) or null | Yes | |
|---|
| endedAt | string (date-time) or null | Yes | |
|---|