Making a Request

When making Cortex API requests, the following are required

  • API Endpoint

  • API Client Key

API Endpoint

Requests must be made over https. The API endpoint takes the following form:

https://<org_api_endpoint>/<org_name>/v2/<api_resource>

Where:

  • org_environment_endpoint is the proper API endpoint for your org environment

  • org_name is the name you provided when signing up

  • api_resource is the Cortex API resource you are accessing. This could be a Cortex object or a custom route.

For example, if your org name was newhealthco and you were accessing the Organization Object in your Cortex dev environment, your fully formed endpoint would look like:

https://api.dev.medable.com/newhealthco/v2/orgs

Request Headers

All API calls require the Medable-Client-Key header, this is populated with an API Key that is generated when you create your app in Cortex. To create your API key, see Generate API Key. Additionally, if you configure your app with CSRF protection, a Medable-Csrf-Token will also be required. In this case, each authenticated request will return an HTTP response header of the same name, and the subsequent request must contain the value of that response header.

Header

Value

Medable-Client-Key

API key. See Generate API Key

Medable-Csrf-Token

When app configured with CSRF protection, authentication and request to authenticated routes will produce a "medable-csrf-token", which must be sent as a request header with each subsequent call.

You must ensure that withCredentials is set to true. Otherwise the secure cookie will not be set on your browser. If you're using one of our mobile SDK's, all of this is handled for you.

Example GET /accounts/me

$.ajax({
    url: "https://api.dev.medable.com/example/v2/accounts/me",
    type: "GET",
    contentType: "application/json; charset=UTF-8",
    dataType : "json",
    xhrFields: {
        withCredentials: true
    },
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq",
        "Medable-Csrf-Token": "MvFkpcS0BCM9qpf4K0pFMyiE57e3VtI5Cb38NfQn6eWiPPp6CqZCOOrAljDZYWnU"
    }
});

Request Methods

GET

GET requests let you read one or many instances of a resource. They typically take one of two forms

List (Many)

`GET /``

Read (One)

GET /<object_name>/<object_id>

GET /<object_name>/<object_id>/<property_path>

POST

POST requests allow you to create a new object instance from the request body. If the request is applied to an array property, the new array elements are pushed onto the existing array.

Create

POST /<object_name>

{
  c_property1: 'value',
  c_property2: true,
  c_property3: [1, 2, 3]
}

Push

POST /<object_name>/<object_id>

{
  c_property3: [4, 5, 6]
}

PUT

PUT requests allow you to update an existing object instance with the contents of the request body for the provided object instance _id. If the request is applied to an array property, the entire array is replaced with the request body.

Update

PUT /<object_name>/<object_id>

{
  c_property1: 'new value'
}

PATCH

PATCH requests let you chain operations together on an object instance in one request. For example, if you have an object instance that you'd like to update the value of one property (ordinarily a PUT request), push a value into an array property (ordinarily a POST request on a path), and delete another property (ordinarily a DELETE request on a path), that would take three requests. However, with a PATCH, you can achieve this in one request containing three operations.

Patch

PATCH /<object_name>/<object_id>

[{
    op: 'set',
    value: { c_property1: false }
},{
    op: 'push',
    path: 'c_array',
    value: 5
},{
    op: 'unset',
    value: {
      c_property1: 1
    }
}]

Patch Operations

Operation

Description

set

Update the value of a document or property json { op: 'set', path: 'c_property1', value: 'new value' } OR json { op: 'set', value: { c_property1: 'new value' } }

unset

Delete a property or properties from the instance. json { op: 'unset', value: { 'c_property1': 1, 'c_property2.c_sub_property1': 1 } }

push

Push a value or array of values into an array property json { op: 'push', path: 'c_property3', value: [4, 5] } OR json { op: 'set', value: { c_property3: [4, 5] } }

remove

Remove a value or array of values from an array. If a value exists multiple times in the array, all values will be removed. json { op: 'remove', path: 'c_property3', value: [1, 3] } OR json { op: 'remove', value: { c_property3: [1, 3] } }

DELETE

DELETE requests allow you to delete the object instance for the provided object _id

DELETE /<object_name>/<object_id> For additional examples and details on making Cortex API requests, see First API Request

Request Size Limit The default maximum request size is 1,024 Kilobytes Timestamp

Last updated

Was this helpful?