MentPass API reference

Authentication and scopes

Send an API key created in API & integrations as Authorization: Bearer mpk_…. Mentors and mentees can create keys when the workspace plan includes API access. 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. Mentor keys act inside the issuer’s workspace. Mentee keys are permanently bound to their own profile: collection reads automatically contain only their data, and another person’s profile, decision, task or meeting ID returns 404, even within the same workspace.

Personal keys allow mentees:read, decisions:read, decisions:write, tasks:read and tasks:write only. They cannot create mentees, assign questionnaires, discover or run workflows, or manage webhooks. Only the owning mentee can list, rotate or revoke a personal key. Account deactivation, a locked profile or a changed role invalidates it.

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.

Mentee keys cannot request private access. Mentor notes, decision review/source provenance and routing emails remain omitted. An authenticated mentee may read summaries, recordings and paginated transcripts of their own meetings, as in the web app, without a mentor private-access grant.

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.

Pagination

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.

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

DecisionReview

DecisionPassage

DecisionSource

Decision

DecisionCreateRequest

DecisionReceipt

DecisionPage

DecisionResponse

DecisionReceiptResponse

MenteeSummary

MenteeDetail

QuestionnaireSelection

MenteeCreateRequest

MenteeCreateReceipt

MenteePage

MenteeResponse

MenteeCreateReceiptResponse

TranscriptSegment

TranscriptPage

Meeting

MeetingDetail

MeetingPage

MeetingResponse

PublishedQuestionnaire

QuestionnairePage

AssignmentRequest

AssignmentReceipt

AssignmentReceiptResponse

Task

TaskCreateRequest

TaskUpdateRequest

TaskReceipt

TaskPage

TaskResponse

TaskReceiptResponse

WebhookEventType

string One of: decision.created, decision.updated, mentee.created, questionnaire.assignment.created, questionnaire.assignment.submitted, task.created, task.updated, workflow.run.ended.

WebhookEndpoint

WebhookEndpointCreateRequest

WebhookEndpointUpdateRequest

WebhookRotateSecretRequest

WebhookEndpointReceipt

WebhookDelivery

WebhookReplayReceipt

WebhookEndpointList

WebhookEndpointResponse

WebhookEndpointReceiptResponse

WebhookDeliveryPage

WebhookReplayReceiptResponse

WebhookEvent

Webhook request body (POSTed to your endpoint). Not an API response.

WorkflowRunStartRequest

Unknown fields are refused with 422 validation_failed.

WorkflowRunReceipt

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

WorkflowRunFull

WorkflowRunRedacted

Returned for a run whose workflow reads questionnaire answers, to a key without private access.

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

WorkflowSummary

A workflow this API key can start runs of: not archived, metered, and with a manual-trigger active version.

WorkflowPage

WorkflowRunEvent