This section outlines the v2 search query syntax. Search query syntax v2 was added in API version 2.7. If you use a previous API version, refer to the documentation for the v1 search query syntax.

Making Read Requests

Authentication

With the exception of the Authenticate and GetSystemInfo methods, all Octopus API methods require that a valid token be passed in the request. If no token is supplied, the request will fail with an error.

The authentication token must be passed as a header - "Authorization" with the specified type Bearer. For example:

Authorization: Bearer {USER_ACCESS_TOKEN}

For more details, please check the Authentication section.

Request structure

Here is an example of a request to visualize possible parameters.

{
  "AbEntry": { // AbEntry is the object name
    "Scope": { // Scope
      "Fields": {
        "Key": 1,
        "Type": 1,
        "CompanyName":1
      }
    },
    "Criteria": { // Criteria
      "SearchQuery": {
        "CompanyName": {
          "$LIKE": "A%"
        }
      },
      "Top": 1
    },
    "GroupBy": { // GroupBy (optional)
        "Fields": []
    },
    "OrderBy": { // OrderBy (optional)
        "PageKey": null,
        "PageSize": 10,
        "Fields": [
            {
                "CreationDate": "ASC"
            }
        ]
     }
  },
  "Compatibility": { // Compatibility (optional)
     "AbEntryKey": "2.0"
  },
  "Configuration": { // Configuration (optional)
      "Drivers": {
          "IAbEntrySearcher": "Maximizer.Model.Access.Sql.AbEntrySearcher"
      }
  }
}

The top-level object in most requests is the object name being passed in the request. In the example above, since this is an AbEntry read request, the entity that is passed is an AbEntry entity.

In the following sections, you will find more details about each part.

Responses

Code

All Octopus API methods return an integer Code to indicate if the request was successful or if it failed.

A Code value of 0 indicates that the request was successful. A negative Code value indicates that an error occurred when processing the request.

Data

If the request is successful, all Octopus API methods return a Data object which contains the results of the request.

For entity methods, the Data object is nested inside the root-level entity object corresponding to the method being called.

The contents of the Data object vary depending on the method being used.

Msg

The Msg property, if present is an array of strings that contain additional informaiton about the request or the response.

For example, the Msg property may contain information about errors or request failures, or about the status of the API itself.

If the request fails for any reason, all Octopus API methods return a Msg array containing information about the error that has occurred to help with troubleshooting.\
If the entity or method that is called is still in a beta or testing release state, the Msg array will contain a message indicating that the method should not be used in a production environment.\

AbEntry read response example

{
  "Code": 0,
  "AbEntry": {
       "Data": [
           {
               "Key":"Q29udGFjdAkwMDEwMDIwMDA2MTMwNjM2NzExNTZDCTU=",
               "Type": "Company",
               "CompanyName":"ABC Wine Shop"
           },
           {
               "Key":"Q29udGFjdAkzNzI2NjIwMDA3MQkx",
               "Type": "Company",
               "CompanyName":"Ansley Wine Merchants"
           }
       ]
   }
}

Error example

{
  "Code": -1,
  "Msg": [
    "The given key is of a type not supported by the target object.(DONOTUPDATE)"
  ]
}

Read Query Syntax