LogoLogo
  • Introduction
  • Features
  • Getting Started
    • Cortex User Guide
      • Organizations
      • Log in
      • Generate an API key
      • Make your first API request
      • Configure the org settings
      • Set up a data model
        • Create custom objects
        • Add custom properties
      • One-to-many relationships
      • Read and write data
      • Making a Request
      • Handling responses
      • Authentication
      • Two-factor authentication
      • Set third-party cookies
      • Connections
      • Upload files
      • Cortex iOS
      • Get started with Swift
      • Cortex service accounts
      • Cortex developer tools
      • Automated Account Notifications
  • Cortex API
    • Overview
    • Objects
      • Objects Overview
      • Organization
      • Account
      • Connections
      • Notifications
      • Stats
      • Logs
      • Export
      • Events
      • Room
    • Object Definition
      • Object Properties
        • Any
        • Binary
        • Boolean
        • Date
        • Document
        • File
        • Geometry
        • List
        • Number
        • ObjectId
        • Reference
        • String
    • Object Types
    • Access Control
    • Querying
      • Query Operators
      • Property Selection
      • Property Access
    • Aggregating
      • Aggregation Operators
    • Scripting
      • Script Types
      • Script Limits
      • ObjectId
      • CortexObject
        • Accounts
        • Views
      • Cursors
      • Operations
      • Script Modules
        • API Module
        • Base64 Module
        • Cache Module
        • Connections Module
        • Console Module
        • Consts Module
        • Counters Module
        • Crypto Module
        • HTTP Module
        • Logger Module
        • Notifications Module
        • Request Module
        • Response Module
        • SAML Module
        • Schemas Modules
        • Script Module
        • Session Module
        • Util.id Module
        • Util.ip Module
        • Util.paths Module
        • XML Module
        • Developer
        • Config
        • Renderer
        • SFTP
        • FTP
        • DB
          • Cursors
          • Driver
      • Static Methods
        • Accounts
        • Views
        • Cursors
      • Audit
      • Environments
      • HTTP Driver
      • Notifications
        • Firebase Cloud Messaging (FCM)
        • Tencent Push Notification Service Configuration
      • Televisit
      • Transforms
      • Localization
      • Available Javascript Libraries
    • Decorators
      • Runtime
        • Acl
        • As
        • Log
        • Profile
      • Static
        • Env
        • Job
        • Object
        • On
        • Policy
        • Route
        • Transform
        • Trigger
    • Expressions
      • Primer
      • Pipelines
      • Operators
      • Accumulators
      • Variables
      • Conditionals
      • Transforms
      • Triggers
      • On
      • Events
    • Faults
      • Fault Reference
  • Releases
    • Cortex Release Notes
      • Cortex API 2.28.3 (R3.4.6)
      • Cortex API 2.28.1 (R3.4.3)
      • Cortex API 2.27.2 (R3.4.1)
      • Cortex API 2.27.1 (R3.3.5)
      • SQL DB Connector 1.3.4 (R3.3.3)
      • Cortex API 2.26.2 (R3.3.1)
      • Cortex API 2.26.1 (R3.2.2)
      • Cortex API 2.26.0 (R3.2.1)
      • SQL DB Connector 1.3.3
      • Cortex API 2.25.0 (R3.1.1)
      • SQL DB Connector 1.3.2 (R3.1.0)
      • Cortex API 2.24.2 (R3.0.2)
      • SQL DB Connector 1.3.1 (R3.0.0)
      • Cortex API 2.24.1 (R2.3.3)
      • Cortex API 2.24.0 (R2.3.2)
      • SQL DB Connector 1.3.0 (R2.3.0)
      • Cortex API 2.23.0 (R2.2.4)
      • SQL DB Connector 1.2.0 (R2.2.0)
      • Cortex API 2.22.2 (R2.1.2)
      • Cortex API 2.22.1 and SQL DB Connector 1.1.1 (R2.0.1)
      • Cortex API 2.22.0
      • Cortex API 2.21.3
      • Cortex API 2.21.2
      • Cortex Web 4.16.0
      • Cortex Web 4.15.1
      • Cortex API 2.20.1
      • Cortex Web 4.14.0
      • Cortex Renderer 1.3.3
      • Cortex API 2.19.4
      • Cortex API 2.19.3 and Cortex Web 4.13.1
      • Cortex Renderer 1.3.2
      • Cortex API 2.19.1
      • Cortex API 2.18.0
      • Cortex API 2.17.6
      • Cortex API 2.17.5
      • Cortex API 2.17.4
      • Cortex API 2.17.3
      • Cortex API 2.17.2
      • Cortex API 2.17.1
      • Cortex API 2.16.0
      • Cortex API 2.15.9
      • Cortex API 2.15.8-1
      • Cortex 2.15.8
      • Cortex API 2.18.1
      • Cortex API 2.16.1
      • Cortex Renderer 1.3.1
      • Cortex Renderer 1.3.0
      • Cortex Renderer 1.2.2
      • Cortex Renderer 1.2.1
      • Cortex Renderer 1.2.0
    • Third-Party License Attribution

© 2025 Medable, Inc. All rights reserved.

On this page

Was this helpful?

  1. Cortex API
  2. Querying

Property Selection

Selecting context response properties using the API is accomplished using paths, include and expand query arguments.

paths

string[]

An array of properties to which the response should be limited.

include

string[]

An array of properties marked as optional that should be included in the response.

expand

string[]

An array of expandable reference that should be expanded in the response.

You can specify any of the above query arguments multiple times. For example, if you need to expand multiple properties, you can do so with the following query string.

?expand[]=account&expand[]=c_customProperty1&expand[]=c_customProperty2

Examples

The example below shows:

  • A reference automatically expanded by selecting a path in the referenced context (creator.name.first).

  • A response limited to the paths specified by the paths[] query arguments.

  • An explicit reference expansion using expand[]=account.

  • An optional path included with include[]=connections.

  • An implicitly included optional path through the use of paths[]=posts;

$.ajax({
    url: "https://api.dev.medable.com/example/patientfiles/550891732390ac1832f3317f?expand[]=account&include[]=connections&paths[]=posts&paths[]=age&paths[]=name.first",
    type: "GET",
    contentType: "application/json; charset=UTF-8",
    dataType : "json",
    headers: {
        "Medable-Client-Key": "GsAqlhnIMzrDeD8V2MBQWq"      
    }
});
{
    "_id": "550891732390ac1832f3317f",
    "object": "patientfile",
    "account": {
        "_id": "550b82336390d9cc34fdd1f0",
        "access": 1,
        "name": {
            "first": "Phineas",
            "last": "Gage"
        },
        "object": "account",
        "roles": []
    },
    "age": 25,    
    "connections": [
        {
            "_id": "550b9a25c59c1ef032ab641c",
            "object": "connection",
            "access": 2,
            "context": {
                "_id": "550891732390ac1832f3317f",
                "object": "patientfile",
                "path": "/patientfiles/550891732390ac1832f3317f"
            },
            "created": "2015-03-20T03:55:17.000Z",
            "creator": {
                "_id": "4578616d706c652055736572",
                "object": "Account",
                "path": "/accounts/4578616d706c652055736572"
            },            
            "state": 1,
            "target": {
                "email": "patient@example.com"                
            }
        }
    ],
    "creator": {
        "_id": "4578616d706c652055736572",
        "name": {
            "first": "Developer"
        },
        "object": "account"
    },
    "name": {
        "first": "Phineas"
    }      
    "posts": []
}

Another example would be to automatically expand into the account reference and limit the properties to first name of the referenced account. The account name may not be accessible to the caller, but the Patient File account property reference has an ACL that allows the name to be read by caller with a Connection to the patient file:

Expand Account Reference

// GET /patientfiles/550891732390ac1832f3317f?paths[]=account.name.first

{
    "_id": "550891732390ac1832f3317f",
    "account": {
        "_id": "550b82336390d9cc34fdd1f0",
        "name": {
            "first": "Phineas"
        },
        "object": "account"
    },
    "object": "patientfile"
}

Limiting Response Properties

Clients can shrink responses by limiting the properties returned by an API request using the paths query argument. Sub paths must be in dot syntax (eg. name.first) and must exist in the object definition.

  • Object responses always include the _id and object properties.

  • Selecting an optional property using paths automatically includes it.

  • Selecting a path in a reference is possible (eg creator.name.first), automatically expanding the referenced context.

Expanding References

References marked as expandable can be expanded into full objects. This can result in less API calls when the client wants to access information in the referenced object.

Depending on the reference property definition, using expand[] may limit the resulting expansion to a set of paths, may grant greater context access than the caller would normally have or allow greater access to a set of properties.

For more information about configuration options, see the section about References.

Optional Properties

Some object properties are marked as optional. Typically, these are non-critical properties that would be expensive to include in every set of responses. For example, the connections and posts properties of objects are optional so wouldn't be included in the result of a call to GET /patientfiles. To retrieve properties marked as optional, use the include[] query argument.

When using paths[], included optional properties will be part of the response.

List Property Selections

Properties that return a list of contexts, such as posts and connections can have selection arguments passed by prefixing them with the property name. For example:

// GET /patientfiles/550891732390ac1832f3317f/connections?paths[]=access

{
    "_id": "550891732390ac1832f3317f",
    "object": "patientfile",
    "connections": {
        "object": "list",
        "hasMore": "false",
        "data: [{
             "_id": "550b9a25c59c1ef032ab641c",
             "object": "connection",
             "access": 2            
         }]
     }         
}

Last updated 3 years ago

Was this helpful?