{ "openapi": "3.1.0", "info": { "title": "Mentornity API", "version": "1.0.0", "description": "Read your programme's members, matches and meetings, and receive webhooks when they change.\n\n**Authentication.** Create a key in the admin panel (Settings, API & webhooks) and send it as `Authorization: Bearer `. A key belongs to one programme and can only read that programme. Keep it on your server; the API sends no CORS headers.\n\n**Environments.** Keys starting `mtk_test_` belong to a sandbox programme with demo data; `mtk_live_` keys to your live programme. Same base URL for both.\n\n**Limits.** Per key: 60 requests per minute (headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`). Per programme: 10,000 requests per UTC day (headers `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset`). Higher limits on request.\n\n**Versioning.** Breaking changes only in a new major version (`/v2`); v1 then stays available for at least 12 months. New fields, endpoints and event types may be added to v1 at any time, so ignore fields you do not know.\n\n**Errors.** JSON `{\"error\": {\"code\", \"message\"}}` with the HTTP status. Every response carries `X-Request-Id`; quote it to support.\n\n**Webhooks.** Register an HTTPS endpoint and choose events in the admin panel. Each event is POSTed as JSON (schema `WebhookEvent`) and signed following the Standard Webhooks specification: headers `webhook-id`, `webhook-timestamp` (Unix seconds) and `webhook-signature` (`v1,` of `..`, keyed with the base64-decoded part of your `whsec_` secret). Reject timestamps older than 5 minutes. Respond 2xx within 10 seconds; otherwise we retry 7 more times over about 2 days (1m, 5m, 30m, 2h, 6h, 12h, 24h). Delivery is at least once and not ordered: deduplicate by `webhook-id` and re-read the object if order matters. An endpoint failing for 72 hours is disabled.", "contact": { "name": "Mentornity support", "email": "info@mentornity.com", "url": "https://mentornity.com/developers" } }, "servers": [ { "url": "https://api.mentornity.com/v1" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key: mtk_live_... or mtk_test_..." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "examples": [ "invalid_api_key" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Person": { "type": "object", "description": "A person. For an erased account only `id` is present.", "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "id" ] }, "ApiKey": { "type": "object", "properties": { "object": { "const": "api_key" }, "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "First characters of the key, for recognition.", "examples": [ "mtk_live_Ab3d" ] }, "environment": { "enum": [ "live", "test" ] }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "programme": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "limits": { "type": "object", "properties": { "requests_per_minute": { "type": "integer" }, "requests_per_day": { "type": "integer" } } } } }, "Scope": { "enum": [ "programme:read", "members:read", "matches:read", "meetings:read" ] }, "Programme": { "type": "object", "properties": { "object": { "const": "programme" }, "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string", "description": "Programme address segment, as in mentornity.com/." }, "environment": { "enum": [ "live", "test" ] }, "language": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "Member": { "type": "object", "description": "A membership: one person in one role in the programme. A person who is both mentor and mentee has two members. Re-adding a removed person creates a new member.", "properties": { "object": { "const": "member" }, "id": { "type": "string" }, "user": { "$ref": "#/components/schemas/Person" }, "role": { "enum": [ "mentor", "mentee" ] }, "status": { "enum": [ "active", "passive", "removed", "converted" ], "description": "`passive`: deactivated; `removed`: removed from the programme; `converted`: the person's role was changed and a new member exists for the new role." }, "joined_at": { "type": "string", "format": "date-time" }, "left_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set when status is not active." }, "updated_at": { "type": "string", "format": "date-time" } } }, "MatchParty": { "type": "object", "description": "A user (`type: user`, with Person fields) or a group (`type: group`, with `name`).", "properties": { "type": { "enum": [ "user", "group" ] }, "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" } }, "required": [ "type", "id" ] }, "Match": { "type": "object", "properties": { "object": { "const": "match" }, "id": { "type": "string" }, "status": { "enum": [ "requested", "active", "completed", "rejected", "canceled", "deleted" ] }, "mentor": { "$ref": "#/components/schemas/Person" }, "mentee": { "$ref": "#/components/schemas/MatchParty" }, "requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Participant": { "allOf": [ { "$ref": "#/components/schemas/MatchParty" }, { "type": "object", "properties": { "role": { "enum": [ "attendee", "guest" ] } } } ] }, "Meeting": { "type": "object", "properties": { "object": { "const": "meeting" }, "id": { "type": "string" }, "status": { "enum": [ "active", "canceled" ] }, "type": { "type": "string" }, "title": { "type": "string" }, "platform": { "type": "string", "description": "Video platform, when one is set." }, "start_at": { "type": "string", "format": "date-time" }, "end_at": { "type": "string", "format": "date-time" }, "organizer": { "$ref": "#/components/schemas/Person" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } }, "canceled_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MemberList": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "description": "Pass as `cursor` to get the next page. Absent on the last page." } }, "required": [ "object", "data", "has_more" ] }, "MatchList": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Match" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "description": "Pass as `cursor` to get the next page. Absent on the last page." } }, "required": [ "object", "data", "has_more" ] }, "MeetingList": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Meeting" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "description": "Pass as `cursor` to get the next page. Absent on the last page." } }, "required": [ "object", "data", "has_more" ] }, "WebhookEvent": { "type": "object", "description": "Body of every webhook POST.", "properties": { "id": { "type": "string", "description": "Event id, also sent as the `webhook-id` header. Use it to ignore duplicates." }, "type": { "enum": [ "member.joined", "member.left", "match.requested", "match.started", "match.ended", "meeting.scheduled", "meeting.canceled", "webhook.test" ] }, "created_at": { "type": "string", "format": "date-time" }, "programme_id": { "type": "string" }, "data": { "description": "The Member, Match or Meeting as it is when the event is sent.", "oneOf": [ { "$ref": "#/components/schemas/Member" }, { "$ref": "#/components/schemas/Match" }, { "$ref": "#/components/schemas/Meeting" }, { "type": "object" } ] } }, "required": [ "id", "type", "created_at", "programme_id", "data" ] } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/me": { "get": { "summary": "Describe the calling key", "description": "Programme, environment, scopes and limits of the key. Needs no scope; use it to test a key.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "401": { "description": "Missing, malformed, unknown or revoked key (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope (`insufficient_scope`) or API access is disabled for the programme (`api_access_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (per key per minute) or `daily_quota_exceeded` (per programme per UTC day). See `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/programme": { "get": { "summary": "Get the programme", "description": "Scope: `programme:read`.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Programme" } } } }, "401": { "description": "Missing, malformed, unknown or revoked key (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope (`insufficient_scope`) or API access is disabled for the programme (`api_access_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (per key per minute) or `daily_quota_exceeded` (per programme per UTC day). See `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/members": { "get": { "summary": "List members", "description": "Mentors and mentees of the programme, current and past.\n\nScope: `members:read`. Ordered by id; page through with `cursor`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1-100 (default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only objects changed at or after this time (RFC 3339 or YYYY-MM-DD). Use it for incremental sync.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "enum": [ "active", "passive", "removed", "converted" ] } }, { "name": "role", "in": "query", "required": false, "description": "mentor or mentee", "schema": { "enum": [ "mentor", "mentee" ] } }, { "name": "user_id", "in": "query", "required": false, "description": "Only this person's memberships.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberList" } } } }, "401": { "description": "Missing, malformed, unknown or revoked key (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope (`insufficient_scope`) or API access is disabled for the programme (`api_access_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (per key per minute) or `daily_quota_exceeded` (per programme per UTC day). See `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Unknown or invalid query parameter (`invalid_parameter`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/members/{id}": { "get": { "summary": "Get a member", "description": "Scope: `members:read`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Member id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "401": { "description": "Missing, malformed, unknown or revoked key (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope (`insufficient_scope`) or API access is disabled for the programme (`api_access_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (per key per minute) or `daily_quota_exceeded` (per programme per UTC day). See `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in this programme (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/matches": { "get": { "summary": "List matches", "description": "Mentor-mentee (or mentor-group) pairings.\n\nScope: `matches:read`. Ordered by id; page through with `cursor`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1-100 (default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only objects changed at or after this time (RFC 3339 or YYYY-MM-DD). Use it for incremental sync.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "enum": [ "requested", "active", "completed", "rejected", "canceled", "deleted" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MatchList" } } } }, "401": { "description": "Missing, malformed, unknown or revoked key (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope (`insufficient_scope`) or API access is disabled for the programme (`api_access_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (per key per minute) or `daily_quota_exceeded` (per programme per UTC day). See `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Unknown or invalid query parameter (`invalid_parameter`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/matches/{id}": { "get": { "summary": "Get a match", "description": "Scope: `matches:read`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Match id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Match" } } } }, "401": { "description": "Missing, malformed, unknown or revoked key (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope (`insufficient_scope`) or API access is disabled for the programme (`api_access_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (per key per minute) or `daily_quota_exceeded` (per programme per UTC day). See `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in this programme (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meetings": { "get": { "summary": "List meetings", "description": "Mentoring meetings scheduled in the programme.\n\nScope: `meetings:read`. Ordered by id; page through with `cursor`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size, 1-100 (default 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` from the previous page.", "schema": { "type": "string" } }, { "name": "updated_since", "in": "query", "required": false, "description": "Only objects changed at or after this time (RFC 3339 or YYYY-MM-DD). Use it for incremental sync.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "enum": [ "active", "canceled" ] } }, { "name": "from", "in": "query", "required": false, "description": "Meetings starting at or after (RFC 3339 or date).", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Meetings starting before (RFC 3339 or date).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingList" } } } }, "401": { "description": "Missing, malformed, unknown or revoked key (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope (`insufficient_scope`) or API access is disabled for the programme (`api_access_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (per key per minute) or `daily_quota_exceeded` (per programme per UTC day). See `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "description": "Unknown or invalid query parameter (`invalid_parameter`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/meetings/{id}": { "get": { "summary": "Get a meeting", "description": "Scope: `meetings:read`.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Meeting id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meeting" } } } }, "401": { "description": "Missing, malformed, unknown or revoked key (`invalid_api_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key lacks the scope (`insufficient_scope`) or API access is disabled for the programme (`api_access_disabled`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (per key per minute) or `daily_quota_exceeded` (per programme per UTC day). See `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such object in this programme (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "member.joined": { "post": { "summary": "A mentor or mentee joined the programme (data: Member).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other status, or no answer in 10 seconds, is retried." } } } }, "member.left": { "post": { "summary": "A member is no longer active: deactivated, removed or converted (data: Member).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other status, or no answer in 10 seconds, is retried." } } } }, "match.requested": { "post": { "summary": "A mentee requested a mentor (data: Match).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other status, or no answer in 10 seconds, is retried." } } } }, "match.started": { "post": { "summary": "A match became active (data: Match).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other status, or no answer in 10 seconds, is retried." } } } }, "match.ended": { "post": { "summary": "A match completed, was canceled, rejected or deleted (data: Match).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other status, or no answer in 10 seconds, is retried." } } } }, "meeting.scheduled": { "post": { "summary": "A meeting was created (data: Meeting).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other status, or no answer in 10 seconds, is retried." } } } }, "meeting.canceled": { "post": { "summary": "A meeting was canceled (data: Meeting).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other status, or no answer in 10 seconds, is retried." } } } }, "webhook.test": { "post": { "summary": "Sent by the Send test event button.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Any other status, or no answer in 10 seconds, is retried." } } } } } }