Introduction

Welcome to the Codementor API! Our APIs let you access and modify your Codementor data programmatically. You can also choose to be notified of events through a webhook. If you have questions about our APIs, please reach out to our support team.

Authentication

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
   -H 'x-codementor-api-key: your-api-key'

Codementor uses API keys to allow access to the API. You can get your key from the API & Webhooks settings page. You'll also be able to revoke and generate a new key on that page.

Codementor expects for the API key to be included in all API requests to the server in a header that looks like the following:

x-codementor-api-key: your-api-key

You must replace your-api-key with your personal API key.

Rate limiting

You can make up to 100 requests per hour. When the rate limit is exceeded, the server will respond with a 429 Too Many Requests HTTP code.

Pagination

{
  // An array containing the actual response items.
  "data": [
    {
      "id": "5eyyfic1fm",
      "finished_at": 1542615971,
      "client": {
        "name": "Luke Skywalker"
      },
      "amount_before_platform_fee": "20.50",
      "length": 310
    }
  ],
  // Whether or not there are more items available after this set.
  "has_more": false
}

Requests that return multiple items will be paginated to 25 items. This applies to all API resources that support "list" methods. For example, you can list all sessions and list monthly payouts. These API methods share a common structure and take a starting_after parameter. starting_after takes an existing item ID value and returns items listed after the named item in reverse chronological order.

Parameters

Name	Description
starting_after	(optional) `starting_after` is an item ID that defines your place in the list. For example, if you receive 25 items from a list request, ending with `5eyyfic1fm`, your subsequent call can include `starting_after=5eyyfic1fm` to fetch the next page of the list.

Dates

All dates in the Codementor API are encoded as a number representing Unix time: the number of seconds that have elapsed since 00:00:00 UTC, January 1, 1970.

Direct Payments

Direct payments are created when mentees/clients send mentors a payment through the Send direct payment button.

List all direct payments

curl -X "GET" "https://dev.codementor.io/api/direct-payments"
  -H "x-codementor-api-key: your-api-key"

{
  "data": [
    {
      "id": "5eyyfic1fm",
      "finished_at": 1542615971,
      "client": {
        "name": "Luke Skywalker"
      },
      "amount_before_platform_fee": "20.50"
    }
  ],
  "has_more": false
}

Returns a list of all direct payments made to you. The list is sorted by creation date with the most recent payment appearing first.

HTTP Request

GET https://dev.codementor.io/api/direct-payments

Parameters

Name	Description
starting_after	(optional) `starting_after` is an item ID that defines your place in the list. For example, if you receive 25 items from a list request, ending with `5eyyfic1fm`, your subsequent call can include `starting_after=5eyyfic1fm` to fetch the next page of the list.

Freelance Jobs

Freelance Jobs are created when clients hire mentors for freelance jobs.

List all freelance jobs

curl -X "GET" "https://dev.codementor.io/api/freelance-jobs"
  -H "x-codementor-api-key: your-api-key"

{
  "data": [
    {
      "id": "5eyyfic1fm",
      "finished_at": 1542615971,
      "client": {
        "name": "Luke Skywalker"
      },
      "amount_before_platform_fee": "20.50"
    }
  ],
  "has_more": false
}

Returns a list of completed freelance jobs. The list is sorted by completion date, with the most recently completed jobs appearing first. Freelance jobs that have been fully refunded aren't included in this list.

HTTP Request

GET https://dev.codementor.io/api/freelance-jobs

Parameters

Name	Description
starting_after	(optional) `starting_after` is an item ID that defines your place in the list. For example, if you receive 25 items from a list request, ending with `5eyyfic1fm`, your subsequent call can include `starting_after=5eyyfic1fm` to fetch the next page of the list.

Payouts

List payouts by month

curl -X "GET" "https://dev.codementor.io/api/payouts/monthly-payouts?payout_month=2018-05"
  -H "x-codementor-api-key: your-api-key"

[
  {
    "paid_at": 1542643200,
    "client": {
      "name": "Luke Skywalker"
    },
    "payment_type": "Freelance Job",
    "created_at": 1542038400,
    "gross_amount": "23.91",
    "platform_fee": "4.30",
    "payout_amount": "19.63"
  }
]

Returns all payouts given a payout_month.

HTTP Request

GET https://dev.codementor.io/api/payouts/monthly-payouts

Parameters

Name	Description
payout_month	`payout_month` is a required parameter in the format of `YYYY-MM`. For example, if you set `payout_month` as `2018-05`, it will return all payout items from May 2018.

Scheduled Sessions

Scheduled sessions are created when mentees/clients request a scheduled session with you. On your dashboard, scheduled sessions are listed under the My Schedule tab. When you receive a new scheduled session, you can programmatically confirm, reschedule, or decline through the APIs below. We recommend using these alongside our webhook events to get notified of any new or updated scheduled sessions.

Confirm

curl -X "POST" "https://dev.codementor.io/api/scheduled-sessions/{scheduled_session_id}/confirm"
  -H "x-codementor-api-key: your-api-key"

{
  "id": "abc123"
}

Confirm a scheduled session

HTTP Request

POST https://dev.codementor.io/api/scheduled-sessions/{scheduled_session_id}/confirm

Parameters

Name	Description
scheduled_session_id	The ID of the scheduled session to confirm

Reschedule

curl -X "POST" "https://dev.codementor.io/api/scheduled-sessions/{scheduled_session_id}/reschedule"
  -H "x-codementor-api-key: your-api-key"

{
  "id": "abc123"
}

Reschedule a scheduled session

HTTP Request

POST https://dev.codementor.io/api/scheduled-sessions/{scheduled_session_id}/reschedule

Parameters

Name	Description
scheduled_session_id	The ID of the scheduled session to reschedule

Decline

curl -X "POST" "https://dev.codementor.io/api/scheduled-sessions/{scheduled_session_id}/decline"
  -H "x-codementor-api-key: your-api-key"

{
  "id": "abc123"
}

Decline a scheduled session

HTTP Request

POST https://dev.codementor.io/api/scheduled-sessions/{scheduled_session_id}/decline

Parameters

Name	Description
scheduled_session_id	The ID of the scheduled session to decline

Sessions

Sessions are created when mentees click the "start session" button in session room.

List all sessions

curl -X "GET" "https://dev.codementor.io/api/sessions"
  -H "x-codementor-api-key: your-api-key"

{
  "data": [
    {
      "id": "5eyyfic1fm",
      "finished_at": 1542615971,
      "client": {
        "name": "Luke Skywalker"
      },
      "amount_before_platform_fee": "20.50",
      "length": 310 // session length in seconds
    }
  ],
  "has_more": false
}

Returns a list of completed sessions. The list is sorted by completion date with the most recently completed session appearing first. Sessions that have been fully refunded aren't included in this list.

HTTP Request

GET https://dev.codementor.io/api/sessions

Parameters

Name	Description
starting_after	(optional) `starting_after` is an item ID that defines your place in the list. For example, if you receive 25 items from a list request, ending with `5eyyfic1fm`, your subsequent call can include `starting_after=5eyyfic1fm` to fetch the next page of the list.

Webhooks

Codementor will send webhook events that notify you any time an event occurs.

Set up webhooks

You can add or update your webhook URL from API & Webhooks settings. If a webhook event fails, we'll retry up to three times.

Checking webhook signatures

# Using Rails

def hook
  payload = request.body.read
  signature_from_header = request.headers['X-Cm-Signature']
  secret = ENV['CODEMENTOR_WEB_SECRET']
  signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret, payload)
  if signature == signature_from_header
    # do whatever you want when request is valid
  else
    render text: "Bad Request", status: 400
  end
end

For security reasons, you shouldn't trust incoming events your webhook URL receives. You should verify signatures to ensure the event was sent from Codementor.

Each webhook event will include a header called X-Cm-Signature. It's a HMAC hex digest of the response body generated using the sha256 hash function and the CODEMENTOR_WEB_SECRET as the HMAC key. You can generate the signature from the payload and compare it with X-Cm-Signature to make sure the request is sent from Codementor.

Event types and payloads

{
  "event_name": "scheduled_session.created",
  "data": {
    "id": "52nbekb9ca",
    "created_at": 1538019834,
    "appointment_timestamp": 1538150400,
    "mentee": {
      "username": "mentee-username",
      "name": "mentee-name"
    },
    "schedule_url": "https://www.codementor.io/m/dashboard/my-schedules/52nbekb9ca"
  }
}

{
  "event_name": "scheduled_session.confirmed",
  "data": {
    "id": "52nbekb9ca",
    "confirmed_at": 1538019834,
    "appointment_timestamp": 1538150400,
    "mentee": {
      "username": "mentee-username",
      "name": "mentee-name"
    },
    "schedule_url": "https://www.codementor.io/m/dashboard/my-schedules/52nbekb9ca"
  }
}

{
  "event_name": "scheduled_session.cancelled",
  "data": {
    "id": "52nbekb9ca",
    "cancelled_at": 1538019834,
    "appointment_timestamp": 1538150400,
    "mentee": {
      "username": "mentee-username",
      "name": "mentee-name"
    },
    "reason": "I have to watch the new Game of Thrones episode!"
  }
}

{
  "event_name": "scheduled_session.declined",
  "data": {
    "id": "52nbekb9ca",
    "declined_at": 1538019834,
    "appointment_timestamp": 1538150400,
    "mentee": {
      "username": "mentee-username",
      "name": "mentee-name"
    }
  }
}

{
  "event_name": "scheduled_session.rescheduled",
  "data": {
    "id": "52nbekb9ca",
    "rescheduled_at": 1538019834,
    "appointment_timestamp": 1538150400,
    "mentee": {
      "username": "mentee-username",
      "name": "mentee-name"
    },
    "schedule_url": "https://www.codementor.io/m/dashboard/my-schedules/52nbekb9ca",
    "note": "I'm not available until this time."
  }
}

Below is a list of events we currently support:

Event Name	Description
`scheduled_session.created`	When a scheduled session is created
`scheduled_session.confirmed`	When a scheduled session is confirmed
`scheduled_session.cancelled`	When a scheduled session is cancelled
`scheduled_session.declined`	When a scheduled session is declined
`scheduled_session.rescheduled`	When a scheduled session is rescheduled

Errors

The Codementor API uses the following error codes:

Error Code	Meaning
400	Bad Request - Your request is invalid.
401	Unauthorized - Your API key is wrong.
404	Not Found - The specified resource could not be found.
409	Conflict - Your request has a conflict with the current state of the target resource.
429	Too Many Requests - You've sent too many requests. Slow down!
500	Internal Server Error - We had a problem with our server. Try again later.

Terms of Use

Last updated: November 21, 2018

The Codementor API aims to further our mentors' experience on Codementor. We're committed to providing a safe and inclusive platform for our mentors and users. These Terms of Use aim to futher this goal. By using our API or webhooks, you agree to follow the Terms listed below:

Your API key and webhook secret is limited to personal use.
The Codementor API cannot be used for any illegal or unethical reasons.
You may not use the API in a way that poses a security vulnerability or threat to our service and users.
The API cannot be used to download data or content from Codementor for spamming purposes.
You may not attempt to use the API in a way that constitues abuse or exceeds rate limits.

If we discover usage that violates these Terms, we reserve the right to suspend your API or webhook access at any time. We may also temporarily suspend your usage rights if we discover any cases that require further investigation. We reserve the right to enforce these policies at our discretion, and these Terms may be amended as our API evolves.

Finally, we may update our API from time to time. We’ll do our best to notify you of any changes, but we suggest checking this documentation periodically for the most updated information.