# 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. |

{% hint style="info" %}
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.
{% endhint %}

{% tabs %}
{% tab title="Example Request (AJAX)" %}

```bash
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"
    }
});
```

{% endtab %}

{% tab title="Example Request (Fetch)" %}

```bash
var request = new Request('https://api.dev.medable.com/example/v2/accounts/me', {
    method: 'GET',  
    credentials: 'include',
    headers: new Headers({
    'Content-Type': 'application/json; charset=UTF-8',
    'Medable-Client-Key': 'GsAqlhnIMzrDeD8V2MBQWq',
    'Medable-Csrf-Token': 'MvFkpcS0BCM9qpf4K0pFMyiE57e3VtI5Cb38NfQn6eWiPPp6CqZCOOrAljDZYWnU'
    })
});
```

{% endtab %}
{% endtabs %}

## 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.medable.com/getting-started/cortex-user-guide/making-requests.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.